MRO Website Documentation

This repository contains documentation for observing at Manastash Ridge Observatory. The documentation can be accessed here.

Writing documentation

Documentation in this site is built using Sphinx, but you don't need to know much about it to write and edit pages. Documentation can be written using either Markdown or reStructuredText (reST). Both allow to format plan text, add links, etc. Markdown is arguably simpler and well supported by GitHub, but reST is a bit more powerful and can be useful if you want to show auto-generated API documentation in Python.

Regardless of what language you choose, you can create a file in docs/ with you new documentation (or edit an existing one) with extension .md if you're using Markdown, or .rst is using reST. You can create the file in a clone or fork of the repository, or directly in GitHub. Edit the file with any content you want to add, then commit the file (remember to use a commit message that's descriptive of what you changed!) This will trigger an automatic rebuild of the documentation (see below for details) and, after about a minute, the changes will be published here.

If you have created a new page and want to add it to the table of contents, edit the file docs/index.rst and add the name of your page to the toctree. For example, if you created a new file docs/evora.md add evora under the toctree section (make sure you keep the same indentation)

.. toctree::
  :maxdepth: 2

  ...
  evora
  ...

You can use directories under docs/. If you created a file docs/some_stuff/stuff1.md add some_stuff/stuff1 in the toctree.

Writing documentation with nox

If you want to write a lot of documentation, it may be helpful to use a nox server that will rebuild the documentation every time you save the file. For that, first clone the repository

git clone git@github.com/uwmro/website-docs

and install the package dependencies

cd website-docs
pip install .

Finally, run the nox server from the root of the repository

nox

That will build the documentation and open a new window in your browser with the website that will be refreshed every time you modify a file. Then use the normal Git commands to commit and push changes.

Deploying the documentation

Every time that you push a change to the repository the documentation is automatically rebuilt and deployed to GitHub Pages. This is basically how it works.

TL;DR when a change to the repository is detected, a GitHub workflow runs that installs Python, runs Sphinx, builds the documentation, and copies the resulting static HTML pages to the gh-pages branch.

When you make and push a change, you can check the Actions page to see your change beeing processed. Sphinx is quite resilient to problems in the code, but if the action fails, something has gone wrong and the static site may be broken. Be sure to fix that if it happens. You can also check the badge at the top of this page to see if the action is working properly.

After the action runs (which should take 30 seconds), a deployment actually updates the GitHub Pages for the documentation (you'll see the deployment changes to Queued and then completes, which should take another 30 seconds). Then you can go here to confirm the changes look fine.