Contribute Docs#
If you contribute a new transformer, or enhance the functionality of a current transformer, most likely, you would have to add or update the documentation as well.
This is Feature-engine’s documentation ecosystem:
Feature-engine documentation is built using Sphinx and is hosted on Read the Docs.
We use the pydata sphinx theme.
We follow PEP 257 for doscstring conventions and use numpydoc docstring style.
All documentation files are located within the docs folder in the repository.
To learn more about Sphinx check the Sphinx Quickstart documentation.
Documents organisation#
Feature-engine has just adopted Scikit-learn’s documentation style, were we offer API documentation, as well as, a User Guide with examples on how to use the different transformers.
The API documentation is built directly from the docstrings from each transformer. If you are adding a new transformer, you need to reference it in a new rst file placed within the api_doc folder.
If you would like to add additional examples, you need to update the rst files located in the user_guide folder.
Docstrings#
The quickest way to get started with writing the transformer docstrings, is too look at the docstrings of some of the classes we already have in Feature-engine. Then simply copy and paste those docstrings and edit the bits that you need. If you copy and paste, make sure to delete irrelevant parameters and methods.
Link a new transformer#
If you coded a new transformer from scratch, you need to update the following files to make sure users can find information on how to use the class correctly:
Add the name of your transformer in these files:
Add an rst file with the name of your transformer in these folders:
That’s it!
Expand the User Guide#
You can add more examples or more details to our current User Guide examples. First, find the relevant rst file for the transformer you would like to work with. Feel free to add more details on the description of the method, expand the code showcasing other parameters or whatever you see fit.
We normally run the code on jupyter notebooks, and then copy and paste the code and the output in the rst files.
Build the documentation#
To build the documentation, make sure you have properly installed Sphinx and the required dependencies. If you set up the development environment as we described in the contribute code guide, you should have those installed already.
Alternatively, first activate your environment. Then navigate to the root folder of Feature-engine. And now install the requirements for the documentation:
$ pip install -r docs/requirements.txt
To build the documentation (and test if it is working properly) run:
$ sphinx-build -b html docs build
This command tells sphinx that the documentation files are within the “docs” folder, and the html files should be placed in the “build” folder.
If everything worked fine, you can open the html files located in build using your browser. Alternatively, you need to troubleshoot through the error messages returned by sphinx.
Good luck and get in touch if stuck!