The Committee on Earth Observation Satellites (CEOS) Open Data Cube (ODC) documentation is a ReadTheDocs website containing documentation about CEOS products related to the ODC and general useful information about using the ODC.
- Managing the Development Environment
- Editing the Documentation
- Deploying the Documentation Publicly to Read the Docs
To start the development environment, run make dev-up
.
To check the status of the development environment, run make dev-ps
- this also shows the port of the development website (should be 8123
, address is localhost:<port>
).
To restart the development environment, run make dev-restart
.
To open a terminal to the development environment, run make dev-ssh
.
This repository uses Sphinx to build HTML documentation from markdown documents - specifically reStructuredText (RST) and Standard Markdown (mainly reStructuredText).
The Sphinx website has a good primer on RST here.
The HTML pages are built on start and for changed markdown files automatically within a few seconds after saving a file - including refreshing any browser tabs viewing the changed HTML files.
To build the HTML pages from the markdown files manually, first connect to the development container: make dev-ssh
.
When in the shell on the container, run these commands to perform the corresponding actions:
command | result |
---|---|
make html |
Build the HTML pages from the markdown |
make apidocs |
Build the API documentation (CEOS ODC Utilities) |
make fullrebuild |
Remove old build products and rebuild the HTML - including for the API documentation |
+--------------------+--------------------------------------------------------------------------------------+ |
Follow these steps to deploy the documentation to readthedocs.org:
- Sign up on the Read the Docs website.
- Once you have signed in, on your dashboard create a new project with the
Import a Project
button. - Select this repository and specify the project details, such as its name and default branch.
- To trigger a build and deployment of the documentation in the repository, click the
Build version
button on the project page.