Scripts and guides for generating documentation for EasyGraph

Repository: easygraph-doc-source

• Scripts and guides for generating documentation for EasyGraph

  • Prerequisites

  • Update ``rst` files <#update-rst-files>`__

    • Edit manually created ``rst` files <#edit-manually-created-rst-files>`__

    • Generate ``rst` files from docstrings as references <#generate-rst-files-from-docstrings-as-references>`__

  • Build HTML from ``rst` files <#build-html-from-rst-files>`__

  • Deploy to easy-graph.github.io

  • Troubleshooting

    • Reference built but not correctly displayed on the website

Prerequisites

It is recommended to have conda/miniconda/anaconda installed on your machine. Clone these repositories and put them inside the same directory:

REPOS=('Easy-Graph' 'easy-graph.github.io' 'easygraph-doc-source')
for i in "${REPOS[@]}"; do
    echo "Cloning: $i"
    git clone "https://github.com/easy-graph/$i"
done

Update rst files

Edit manually created rst files

Go to easygraph-doc-source/docs_using_sphinx, and hand-edit / remove / add any rst files outside of reference.

Generate rst files from docstrings as references

cd easygraph-doc-source/docs_using_sphinx
make gen-rst
# generated rst files in reference dir

Build HTML from rst files

• Install dependencies in requirements.txt with the following command: pip install -r requirements.txt.

• Run make html. The updated pages locate in ./_build/html.

Deploy to easy-graph.github.io

• Sync all the files under ./_build/html to repository easy-graph.github.io:

cd easygraph-doc-source
make sync-doc-pub-repo

• Push the changes of these two repository to their remotes

Troubleshooting

Reference built but not correctly displayed on the website

• Check the toctree of reference.rst, you may need to manually update the section to reflect the built references.