Documentation

Note

We are currently in process of switching our documentation tool from sphinx to mkdocs. Currently the files located in python/docs are required for sphinx’s CI validation step (docs-test) as they are the configuration files for how sphinx works in documenting Valkey GLIDE. Once we switch to mkdocs, sphinx related files and validation should be removed, and mkdocs’s files and validation should be used instead.

Note

By default, mkdocs should still be using Google’s Python Docstring Style so the “Documentation Style” page still be valid.

Caution

docs/index.rst has manual modifications to it and should NOT be deleted. Modify this file with caution.

We follow the Google Style Python Docstrings format in our documentation. For our documentation tool, we use sphinx.

To run sphinx, execute the following:

cd $HOME/src/valkey-glide/python
source .env/bin/activate
pip3 install -r dev_requirements.txt
cd docs
sphinx-apidoc -o . ../python/glide
make clean
make html # or run make help to see a list of available options

In docs/_build you will find the index.html page. Open this file in your browser and you should see all the documented functions.

However, some stylings may not be implemented by this Google format. In such cases, we revert back to the default style that sphinx uses: reStructuredText. An example of this is shown for hyperlinks below.