Lets-Plot documentation site

This repository contains sources for building and publishing the Lets-Plot project documentation site using Sphinx and GitHub Pages.

Build and publish documentation site

All commands should be run from the repository root.

1. Create conda environment lets-plot-docs from file environment.yml:

   conda env create --file ./environment.yml

   If you already have this environment or environment.yml has been changed, you need to update the environment. In that case, run:

   conda env update --name lets-plot-docs --file ./environment.yml --prune

2. Activate this environment:

   conda activate lets-plot-docs

3. Only for Windows users, run:

   conda install m2w64-toolchain

4. Install Lets-Plot Python package:

   pip install lets-plot

5. If the document source/_shared/index_body.rst needs to be updated, run:

   python utils/update_index.py -i %PATH-TO-README_PYTHON.md%

6. Build documentation (HTML):

   sphinx-build -b html ./source ./docs

7. Check docs/index.html in your browser.

8. Commit and push new changes.

Directory structure

• data/ - constists of datasets for the demo notebooks.
• docs/ - source folder for the documentation site; generated by the sphinx-build command.
• jupyter_execute/ - provides executable code on the site pages due to the jupyter-execute extension; generated by the sphinx-build command.
• source/
  • _ext/ - contains the custom Sphinx extensions.
  • _shared/ - directory with ReST documents included in other places through the .. include:: directive.
    • index_body.rst - body of the site index page; should be generated from the README_PYTHON.md document by using the update_index.py util.
  • _static/ - standard Sphinx folder that contains custom static files (such as style sheets or script files).
  • _templates/ - standard Sphinx folder for custom HTML templates.
  • gallery/ - gallery notebooks produced by the sphinx_gallery extension; generated by the sphinx-build command.
  • gallery_py/ - gallery examples as Python files produced by the sphinx_gallery_jupyter extension; generated by the sphinx-build command.
  • pages/ - static pages of the documentation site in the ReST format.
  • conf.py - Sphinx configuration file.
  • index.rst - source for the main page of the site.
• source_gallery/ - bunch of the jupyter notebooks - source for the documentation gallery.
• utils/update_index.py - util for preparation the index page of the documentation site; run python utils/update_index.py -h for details.
• environment.yml - list of the python packages used by the documentation; see Build and publish documentation site section.

License

Code and documentation released under the MIT license. Copyright © 2019-2021, JetBrains s.r.o.