Skip to content

Latest commit

 

History

History
124 lines (79 loc) · 2.76 KB

README.md

File metadata and controls

124 lines (79 loc) · 2.76 KB
Raw

Documentation

This is the Mass Open Cloud documentation repository.

Organzation

Documentation files are written in Markdown and are stored in the docs/source directory.

Adding a new section

Major sections are defined in docs/source/index.rst in the toctree block:

.. toctree::
   :maxdepth: 2

   networking/index.rst
   hardware/index.rst

To add a new section:

  1. Create the corresponding directory as a subdirectory of docs/source (e.g., docs/source/mysection).

  2. Create an index.rst file in the new directory (so, docs/source/mysection/index.rst) that looks like this:

    My Section
==========

.. toctree::
   :maxdepth: 2
   :glob:

   *

  3. Update the main docs/source/index.rst to include your new section:

    .. toctree::
   :maxdepth: 2

   networking/index.rst
   hardware/index.rst
   mysection/index.rst

Adding a new document

Create your document in an existing section directory. The document should start with a level 1 heading:

# This is my document

Rendering

You can render the documentation locally by installing Sphinx and using the Makefile. These instructions are appropriate for Linux and MacOS users; if you are using Windows, please see the Windows README.

Requirements

In order to build the documentation you will need a recent version of Python and the make utility.

If this is your first time rendering the documentation

Start in the top level of this repository.

  1. Create and activate a Python virtual environment:

    $ python -mvenv .venv
$ . .venv/bin/activate

  2. Install the required software:

    $ pip install -r requirements.txt

  3. Build the documentation using make:

    $ make -C docs html

If you previously run the installation steps

If you have already run the above steps and you have an existing .venv directory, you can skip the installation steps:

$ . .venv/bin/activate
$ make -C docs html

Opening the documentation in your browser

  1. You can directly open the file docs/build/html/index.html in your browser. Under Linux, this will probably work:

    $ xdg-open docs/build/html/index.html

    Under MacOS, you can use the open command:

    $ open docs/build/html/index.html

    And of course you can just use the "Open..." menu item in your browser.

  2. You can start a simple http server and then point your browser at a local URL. To start a server on port 8000:

    $ cd docs/build/html
$ python -m http.server 8000

    Now point your browser at http://localhost:8000