documentation.rst 2.7 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364
  1. .. _tripal_rtd:
  2. Contributing to the Documentation
  3. ==================================
  4. The Tripal documentation is written in `**Restructured Text** <http://docutils.sourceforge.net/rst.html>`_, compiled with `Sphinx <http://www.sphinx-doc.org/en/master/usage/quickstart.html>`_, and built/hosted with `ReadTheDocs <https://readthedocs.org/>`_. The ``docs`` directory, when compiled, is hosted at https://tripal.readthedocs.io/en/latest/.
  5. For minor changes, you can simply `Edit the file using the Github editor <https://help.github.com/articles/editing-files-in-your-repository/>`_, which will allow you to make a Pull Request. Once approved, your changes will be reflected in the documentation automatically!
  6. Guide
  7. ------
  8. Install Sphinx
  9. ~~~~~~~~~~~~~~~~~
  10. For minor changes, you don't need to build the documentation! If you want to see how your changes will look on the built site, however, you will need Sphinx installed.
  11. For more information, please see the Sphinx setup guide:
  12. http://www.sphinx-doc.org/en/master/usage/quickstart.html
  13. Building your changes
  14. ~~~~~~~~~~~~~~~~~~~~~~~
  15. For more extensive edits, or when contributing new guides, you should build the documentation locally. From the ``docs`` root (eg ``/var/www/html/sites/all/modules/tripal/docs/``, execute ``make html``. The built site will be in ``docs/_build/html/index.html``.
  16. Tripal conventions
  17. ~~~~~~~~~~~~~~~~~~~~~~~
  18. Please follow these guidelines when updating our docs. Let us know if you have any questions or something isn't clear.
  19. Please place images in the same folder as the guide text file, following the convention [file_name].[n].[optional description].[extension]. For example, ``configuring_page_display.3.rearrange.png`` or ``configuring_page_display.1.png`` are both located in ``docs/user_guide/`` and are part of the ``configuring_page_display.rst`` guide.
  20. We currently use the following syntax:
  21. .. code-block:: rst
  22. Title of File (using title case)
  23. =================================
  24. Introduction text.
  25. Section Title
  26. -------------
  27. We use double backticks to indicate ``inline-code`` including file names, function and method names, paths, etc.
  28. Longer code-blocks should begin with the ``.. code-block:: [type]`` directive and should be indented at least one
  29. level. There should also be a blank line before and after it as shown below.
  30. .. code-block:: sql
  31. if ($needs_documentation) {
  32. use $these_guidelines;
  33. $contribute_docs = $appreciated;
  34. }
  35. Section 1.1 Title
  36. ^^^^^^^^^^^^^^^^^
  37. The use of appropriate sections makes reading documentation and later specific details easier. Sub sections such
  38. as this one will be hidden unless the main section is already selected.
  39. ```