When TrueOS began using Sphinx for documentation generation, all Handbook files were added to their own repositories on Github: TrueOS, Lumina, SysAdm. Updating documentation, and especially screenshots, is a relatively simple method to help out with TrueOS, but there are a few standards that contributors should consider:
- Save all screenshots. Maintaining an archive of all used screenshots is very useful. To that end, do not delete any screenshots from the docs repository’s images folder. Instead, add the new screenshot by sequentially naming it after the image it is replacing. For example, image trueos1a.png is out of date. I save the new screenshot trueos1b.png to the images folder and open the corresponding .rst file to make the update.
- All screenshots are in .png format. Compressing the image is encouraged, but not required.
- Maintain .rst formatting. Personal recommendations for editing Handbook .rst files are kate and the lumina text editor, but many different text editors are available. Generally, when editing an .rst file to replace an existing screenshot, the only element to update is the pathway to the new screenshot, as seen here:
.. figure:: images/lumina1e.png
: Lumina Desktop
:numref:`Figure %s ` is a screenshot of Lumina using its
default settings. The user has clicked the "|lumina|" icon in order to
open the start menu.
In this block example, I update the outdated image lumina1e.png by deleting the e and typing f in its place, as long as I remember to follow the other standards of image location and naming. I don’t need to alter any other elements of the document.
- Edit the package plist (trueos-docs repository only). TrueOS uses Jenkins to automatically build and push the various Handbooks to their web locations. Jenkins requires a properly maintained plist in order to build the Handbooks. Each screenshot has its own line in the plist, and it is important to update this file to replace the old image’s entry with the new screenshot. Again, as long as you maintain the other standards, only update the image names.
- Build test before pushing any changes. I highly recommend to always build a local copy of the documentation with Sphinx (pkg name: py27-sphinx) before pushing any changes to the documentation repositories.
If you have any questions about contributing to the TrueOS documentation, feel free get in touch with the developers and other TrueOS contributors on Gitter, Discourse, or one of our many other community options.