docs(website): document custom step implementation

[jcrist]

Once the Step interface solidifies a bit more, we may want to document how users can implement their own Step subclass. We probably won't want to document for external usage for a while (the interface is still in flux and not really user-facing). Docs on the internals may be useful before then for aiding in contributions.

[deepyaman]

https://github.com/ibis-project/ibis-ml/pull/116#issuecomment-2150989019 needs to be re-raised and reviewed with feedback incorporated at some point. Raise priority to P1, as @jitingxu1 already did significant work.

[ahaan1984]

I'd like to try and work on this issue. Would appreciate it if I could get some guidance.

[deepyaman]

I'd like to try and work on this issue. Would appreciate it if I could get some guidance.

Hi @ahaan1984. Thanks for your interest in helping out with the docs for IbisML!

@jitingxu1 did quite a lot of work on this in https://github.com/ibis-project/ibis-ml/pull/116; what would be great is if you can:

1. Run through the instructions in that PR, making sure it's clear to you and works (especially as somebody who hasn't created a custom step before).
2. Make updates to the doc, including based on the review in the PR. If there is anything else you want to change from a wording perspective, feel free to propose!

At the same time, it would be great to make sure you can build the docs. Unfortunately, we haven't added contributor docs yet, either. 😅 (If this is something you would like to do, more than happy to accept!)

We use Quarto to build the docs. You can install the CLI from the website. You should also install all of the project requirements in your development environment (likely using something like venv or Conda for isolation). You can install using pip install -e '.[doc]' from the root of the cloned repository.

Once everything is set up, from the docs/ directory:

1. quartodoc build: build the API docs
2. quarto render: render the website
3. quarto preview: view the website on your local browser

Hopefully this helps to get started!

[ahaan1984]

Hi @deepyaman. While trying to build the docs, while running the quartoc build command, I encountered the following error:

We use Quarto to build the docs. You can install the CLI from the website. You should also install all of the project requirements in your development environment (likely using something like venv or Conda for isolation). You can install using pip install -e '.[doc]' from the root of the cloned repository.

I have followed the steps as mentioned, and I have used venv for virtual environment. Additionally, I have tried manually installing the griffe module using pip, and I have also re-installed Python itself. I'd appreciate it if I could get some guidance in fixing this error.

[deepyaman]

Hi @deepyaman. While trying to build the docs, while running the quartoc build command, I encountered the following error:

We use Quarto to build the docs. You can install the CLI from the website. You should also install all of the project requirements in your development environment (likely using something like venv or Conda for isolation). You can install using pip install -e '.[doc]' from the root of the cloned repository.

I have followed the steps as mentioned, and I have used venv for virtual environment. Additionally, I have tried manually installing the griffe module using pip, and I have also re-installed Python itself. I'd appreciate it if I could get some guidance in fixing this error.

@ahaan1984 Griffe 1.x was released recently, and it looks like Quartodoc has not yet released support (I see the work done in https://github.com/machow/quartodoc/pull/359). In the meantime, you'll need to pip install 'griffe<1'—hopefully, that will do it!