Documentation

PlantCV documentation is hosted on Read the Docs. Using Read the Docs allows the documentation to be versioned along with the code. Because Read the Docs supports static content build tools like Mkdocs, documentation can be written in simple Markdown format that will be built into HTML automatically whenever a new version of code is pushed to the PlantCV GitHub repository.

Updating PlantCV documentation

Follow the contribution guide to learn how clone a copy of the PlantCV repository, edit files, and generate a pull request to merge your updates back into the main repository. Changes to PlantCV should be done in a branch, and pull against the main branch which corresponds to the latest version of the documentation on Read the Docs.

The documentation files are all located in the docs folder. If you are editing existing documentation, the Markdown files can be edited in any plain text editor or in the GitHub web interface. See here for an overview of Markdown format.

When adding new documentation, a new Markdown file should be added to the docs folder with a descriptive name. If the documentation page will include any images, these should be added to as subfolder specific to the new documentation within the docs/img subdirectories. To keep the size of the repository down, please only use jpeg images at a maximum width of 400px unless there is a specific need for a different format or size. Please see other existing documentation files for general style guidelines. Finally, new documentation files need to be referenced in the mkdocs.yml file in the main repository folder. This is done by adding the new file as a node in the table of contents tree. In the example below a new documentation file was added to the Documentation, Tutorials, and PlantCV Namespace sections.

nav:
- Home: index.md
- Documentation:
  - Installation: installation.md
  - 'New general documentation': new_doc.md
  - Tutorials:
    - 'VIS workflow': vis_tutorial.md
    - 'New tutorial': new_tutorial.md
  - - 'PlantCV Namespace':
    - 'Analyze color': analyze_color.md
    - 'New function': new_function.md

mkdocs can be used to test that the new documentation can be built correctly locally before submitting to GitHub. From the root of a local plantcv repository clone:

mkdocs build --theme readthedocs --site-dir _site

A clean build will output the messages:

INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: plantcv/_site
INFO    -  Documentation built in 6.29 seconds

The _site folder (ignored by git) will contain the static HTML files that can be viewed with a web browser to double check that the new documentation build looks as intended.

Once a pull request is merged into the repository, a new version of the documentation will be built automatically.