Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-03-26 02:11:55 +00:00
Code Issues Packages Projects Releases Wiki Activity

restructure to account for new theme, add new build process, update readme

Browse Source
This commit is contained in:
Lucy Cifferello
2021-12-13 23:02:47 -07:00
parent 4e59b06c85
commit 1e756e5cfa
669 changed files with 61332 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
README.md
View File

@@ -2,41 +2,44 @@
At Start9, we see great value in maintaining clear and accurate documentation for our already simple and friendly products. These docs are a continuous work-in-progress, and we welcome contributions from our partners and customers.
## Runbook
## Toolkit
This project uses:
- [Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html)
- [Restructured Text](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html)
- [Sphinx Book Theme](https://sphinx-book-theme.readthedocs.io/)
These are the basic tools this project uses:
### Dependencies
### Markup language
Install [python3](https://docs.python-guide.org/starting/install3/osx/)
Docs are written in [RestructuredText](https://www.sphinx-doc.org/es/master/usage/restructuredtext/index.html). RestructuredText is a file format for textual data used primarily for technical documentation.
Install sphinx and dependencies:
```
brew install sphinx-doc
pip3 install sphinx-autobuild
pip3 install sphinx-book-theme || pip install git+https://github.com/executablebooks/sphinx-book-theme.git@master
pip3 install sphinxcontrib.yt
pip3 install sphinx-multiversion
```
### Sphinx
### Development
The tool we used to converts [restructuredText](https://www.sphinx-doc.org) and Markdown to HTML.
Sphinx also has directives and extensions to add additional options for formatting the text.
Run: `sphinx-autobuild source build/html` to activate a live-reload environment on `localhost:8000`.
### Scylla Sphinx Theme
To run in development mode when actively changing js/css files run: `sphinx-autobuild source build/html source/_static/js/main.js source/_static/default.css`. This will auto reload with changes to noted files.
A customized version of the [theme](https://github.com/scylladb/sphinx-scylladb-theme) used by Scylla documentation projects. It also adds a set of custom functionalities and styles.
The main configuration file for this project is located at `./source/conf.py`.
### Multiversion extension
The navigation structure is aligned with the folder/file organization under `./source/`. This is where the individual page `.rst` files live and can be edited.
The [extension](https://github.com/Holzhaus/sphinx-multiversion) used to build docs for different versions.
If any css or table of contents organization changes, run: `make clean html`.
## Dependencies
Install [pyenv](https://github.com/pyenv/pyenv)
## Development
When editing these files, begin a livereload environment by running `make preview` while in the `./docs/` directory.
When editing any css or table of contents organization changes, the livereload environment must be ended and `make clean` run before starting `make preview` again.
### Versioning
- Build for versioning (must be on master) branch: `make multiversion`
- To view version metadata: `make multiversionpreview`
## Contributing to the docs
If you notice a mistake in the docs, or you have an idea for improving them, we would like to know about it. You can either fix the mistake yourself and submit a pull request, or you can report the mistake by submitting an issue.
If you notice a mistake in the docs, or you have an idea for improving them, we would like to know about it. You can either fix the mistake yourself and submit a pull request, or you can report the mistake by submitting an `issue <https://github.com/Start9Labs/documentation/issues>`__ .
### Submitting an issue
@@ -44,21 +47,13 @@ Click on the "Issues" tab in the top navbar. Provide a good title and describe c
### Submitting a pull request
Click on the "Pull requests" tab in the top navbar. Select the green "New pull request button" in the top right section. Select your branch for the compare dropdown, and master as the base. Provide an appropriate title and summary of the changes in the pull request description. Changes will be reviewed and merged when satisfactory.
Click on the "Pull requests" tab in the top navbar. Select the green "New pull request button" in the top right section. Select your branch for the compare dropdown, and master as the base. Provide an appropriate title and summary of the changes in the pull request description. Changes will be reviewed and merged when satisfactory.
## Helpful Resources
- [Lists in RST](https://sublime-and-sphinx-guide.readthedocs.io/en/latest/lists.html)
## Updating theme
To update Sphinx Book Theme:
- `pip uninstall sphinx-book-theme` (needed to properly propagate new changes for some undetermined reason)
- `pip install sphinx-book-theme==<tag_version>` || `pip install git+https://github.com/executablebooks/sphinx-book-theme.git@<branch_name>` eg. `pip install sphinx-book-theme==0.0.42`
To deploy theme update:
- Build and publish according to production release process
## Versioning
- Build for versioning: `sphinx-multiversion source build/html`
- To view version metadata: `sphinx-multiversion source build/html --dump-metadata`
### Sphinx and RST syntax guides:
http://sphinx-doc.org/rest.html
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
http://www.siafoo.net/help/reST
http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
https://sublime-and-sphinx-guide.readthedocs.io/en/latest/lists.html