Contributing to These Docs¶
Additions, improvements, and corrections to these docs are always welcome.
The quickest way to fix typos, etc. on existing pages is to use the Edit on GitHub link in the upper right corner of the page to get to the online editor for the page on GitHub.
For more substantial work, and to add new pages, the instructions below explain how to:
clone the repository from GitHub
set up a conda environment in which you can build the docs locally instead of having to push commits to GitHub to trigger a build on readthedocs.org
build the docs with your changes, and preview them in Firefox
Getting the Repo¶
Clone the MIDOSS documentation repository from GitHub with:
$ git clone email@example.com:MIDOSS/docs.git
$ git clone https://github.com/MIDOSS/docs.git
Docs Build Environment¶
Setting up an isolated docs build environment using Conda is recommended. Assuming that you have the Anaconda Python Distribution or Miniconda3 installed, you can create and activate an environment called midoss-docs that will have all of the Python packages necessary for building the documentation with the commands:
$ cd docs $ conda env create -f environment.yaml $ conda activate midoss-docs
To deactivate the environment use:
(midoss-docs)$ conda deactivate
If you are using a version of conda older than 4.4.0, the commands to activate and deactivate the environment are:
$ source activate midoss-docs
(midoss-docs)$ source deactivate
You can check what version of conda you are using with conda --version.
Building and Previewing the Documentation¶
The MIDOSS documentation is written in reStructuredText and converted to HTML using Sphinx.
Creating a Docs Build Environment as described above includes the installation of Sphinx.
Building the documentation is driven by the
With your midoss-docs environment activated,
(midoss-docs)$ make clean html
to do a clean build of the documentation. The output looks something like:
Removing everything under '_build'... Running Sphinx v1.7.5 making output directory... loading pickled environment... not yet created building [mo]: targets for 0 po files that are out of date building [html]: targets for 3 source files that are out of date updating environment: 3 added, 0 changed, 0 removed reading sources... [100%] index looking for now-outdated files... none found pickling environment... done checking consistency... done preparing documents... done writing output... [100%] index generating indices... writing additional pages... search copying static files... done copying extra files... done dumping search index in English (code: en) ... done dumping object inventory... done build succeeded. The HTML pages are in _build/html.
The HTML rendering of the docs ends up in
You can open the
index.html file in that directory tree in your browser to preview the results of the build.
To preview in Firefox from the command-line you can do:
(midoss-docs)$ firefox _build/html/index.html
Version Control Repository¶
Documentation tasks, bug reports, and enhancement ideas are recorded and managed in the issue tracker at https://github.com/MIDOSS/docs/issues.
The MEOPAR MIDOSS Project Documentation is copyright 2018-2020 by the MIDOSS project contributors, The University of British Columbia, and Dalhousie University.
It is licensed under a Creative Commons Attribution 4.0 International License.