How to Prepare Documentation

David Antos

May 2018

Where

ELIXIR Data Transfer documentation is published on http://elixir-data-transfer-docs.readthedocs.io/. Its source codes are kept on https://github.com/david-antos/elixir-data-transfer-docs. When changes are pushed to GitHub, Read the Docs published version gets regenerated automatically.

How

reStructuredText

The documentation is preferrably written in reStructuredText format. Using Markdown is also possible, but it is much less standardised. For good reasons to prefer reStructuredText, see http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/.

If you’re new to reStructuredText, there are some docs for you:

Please note that reStructuredText is extremely picky to text indentation. If you run into trouble, check your indentation first.

Necessary local software

You’ll need
  • git
  • any text editor
  • (optional but recommended) Sphinx will allow you to generate the documentation locally

Writing new documentation/article

Kindly add a folder to the repository for a new article to keep it neat. Write the documentation (using .rst file suffix is recommended). Make a link to the documentation from index.rst.

If you have Sphinx installed, you can prepare local preview of your docs. Just run

make html

(or a windows bat equivalent) in the main folder and point your browser to _build/html/index.html. Or any other format you like.

Please note: to keep things simple, we use built-in Sphinx style for local html output. It differs from the style on the Read the Docs site. The reason is not to complicate things beyond necessary, you’d have to install the Read the Docs style locally.

Tips and tricks

If you’re unlucky enough to have your documentation in Google Docs or any other format (even lacking proper logical markup), you may try Pandoc to convert it.

Initial conversion of this group’s documentation in Google Docs has been produced by exporting to docx, converting according to Mpei’s Blog and heavily edited by hand.

Working with Git repository

For the time being, there is no urge for a strict “editorial process” to be put in place. The core team members of data transfer may have write access to the GitHub repository. Please keep in mind that committing to the repository directly rebuilds the documentation on the public website. The branch-to-be-published is “master”. You are therefore advised to push material suitable for public viewing (it doesn’t have to necessarily be finished, of course) and compilable. Check your work locally or at least check the public website after pushing changes. Use a branch for development.

Ask David or any other collaborator to grant you access to the repository (including your GitHub identity to this request speeds things up).

If you are an outside contributor or if you feel you’d prefer your documentation to be extensively reviewed before publishing, use the “fork and pull” model. Fork the repository, create a branch, do your stuff, and create a pull request. Refer to https://help.github.com/categories/collaborating-with-issues-and-pull-requests/ if you need to get familiar with the process.

Contacts

For write access to the GitHub repo, requirements to add plugins (keep it reasonable, please), change the config of Read the Docs, please contact David Antos (david (dot) antos (atsymbol) cesnet.cz).