Each heading level creates a sub-section in the global table of contents tree available when the documentation is built. In the primary (web) version of the documentation, this only shows four levels deep from the top level of the documentation. Please refrain from using more heading levels than will show in this tree as it makes navigating your document difficult. If you must use this many heading levels, it is a good sign that your document should be split up into multiple pages.

People can’t navigate to your new page if they can’t find it. Neither can Sphinx. That’s why you need to add new pages to Sphinx’s table of contents.

You can do this by adding the page to the index.rst file in the same directory that you created it. For example, if you create a file called “newpage.rst”, you would add the line marked with a chevron (>) in the nearest index:

The order matters. If you would like your page to appear in a certain place in the table of contents, place it there. In the previous example, newpage would be added to the end of this table of contents.

Your edits must not introduce any warnings into the documentation build. If any warnings occur, the build will fail and your pull request will be marked with a red ‘X’. Please ensure that your RST is valid and correct before you create a pull request. This is done automatically (via sphinx-build crashing with your error) if you follow our build instructions below.

If you’d like to build this documentation before sending a PR (which you should), follow these instructions on your local copy of your fork of the repository.

The documentation can be built by running ./build.sh in the root of this repository. The script will also create a virtual build environment in ~/ubportsdocsenv if none is present.

If all went well, you can enter the _build/html directory and open index.html to view the UBports documentation.

If you have trouble building the docs, the first thing to try is deleting the build environment. Run rm-r~/ubportsdocsenv and try the build again. Depending on when you first used the build script, you may need to run the rm command with sudo.

If you would like to write documents for UBports but are not comfortable writing ReStructuredText, please write it without formatting and post it on the UBports Forum in the relevant section (likely General). Someone will be able to help you revise your draft and write the required ReStructuredText.

If you’ve written a complete document in ReStructuredText but aren’t comfortable using Git or GitHub, please post it on the UBports Forum in the relevant section (likely General). Someone will be able to help you revise your draft and submit it to this documentation.