https://github.com/tddschn/easygraph-doc-source
Scripts and guides for generating documentation for EasyGraph
https://github.com/tddschn/easygraph-doc-source
easygraph furo python-easygraph sphinx
Last synced: about 1 year ago
JSON representation
Scripts and guides for generating documentation for EasyGraph
- Host: GitHub
- URL: https://github.com/tddschn/easygraph-doc-source
- Owner: tddschn
- Created: 2023-01-11T07:13:43.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-05-30T10:16:58.000Z (about 3 years ago)
- Last Synced: 2025-01-17T04:47:53.191Z (over 1 year ago)
- Topics: easygraph, furo, python-easygraph, sphinx
- Language: HTML
- Homepage: https://github.com/tddschn/easygraph-doc-source
- Size: 37.3 MB
- Stars: 2
- Watchers: 2
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Scripts and guides for generating documentation for EasyGraph
Repository: [easygraph-doc-source](https://github.com/easy-graph/easygraph-doc-source)
- [Scripts and guides for generating documentation for EasyGraph](#scripts-and-guides-for-generating-documentation-for-easygraph)
- [Prerequisites](#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](#deploy-to-easy-graphgithubio)
- [Troubleshooting](#troubleshooting)
- [Reference built but not correctly displayed on the website](#reference-built-but-not-correctly-displayed-on-the-website)
## Prerequisites
Clone these repositories and put them inside the same directory:
```bash
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
```bash
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`:
```bash
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.