c6f63cca67
* add image and update flashing guide * Touchups: change linux/mac/win options to non-sequential list, finesse some final wording * Add Umbrel2Embassy guide into FAQ * Update faq-embassy.rst * Update flashing.rst Co-authored-by: gStart9 <george@start9labs.com> Co-authored-by: kn0wmad <39687477+kn0wmad@users.noreply.github.com>
Start9 Documentation
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.
Toolkit
These are the basic tools this project uses:
Markup language
Docs are written in RestructuredText. RestructuredText is a file format for textual data used primarily for technical documentation.
Sphinx
The tool we used to converts restructuredText and Markdown to HTML. Sphinx also has directives and extensions to add additional options for formatting the text.
Scylla Sphinx Theme
A customized version of the theme used by Scylla documentation projects. It also adds a set of custom functionalities and styles.
Multiversion extension
The extension used to build docs for different versions.
Dependencies
Install python3 Install poetry Install pyenv
For installations with MacOS:
brew install python3
brew install poetry
Project Setup
- Clone this repository and enter the project folder:
git clone https://github.com/Start9Labs/documentation.git && cd documentation
- Install theme submodule:
git submodule update --init
- Navigate to the
sitefolder and start the project:
cd site
make clean && make preview
Development
When editing these files, begin a livereload environment by running make preview while in the ./site/ 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.
If you edit something inside sphinx-scylladb-theme, you will need to cd into that directory and run npm run build.
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 <https://github.com/Start9Labs/documentation/issues>__ .
Submitting an issue
Click on the "Issues" tab in the top navbar. Provide a good title and describe clearly the mistake or improvement.
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.
Helpful Resources
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