Scripts and guides for generating documentation for EasyGraph

Repository: easygraph-doc-source

• Scripts and guides for generating documentation for EasyGraph
  • Prerequisites
  • Update rst files
    • Edit manually created rst files
    • Generate rst files from docstrings as references
  • Build HTML from rst files
  • Deploy to easy-graph.github.io
  • Troubleshooting
    • Reference built but not correctly displayed on the website

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.