Scripts and guides for generating documentation for EasyGraph#

Repository: easygraph-doc-source

Prerequisites#

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.

  • 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.