Source

ucommentapp-maintained / GUIDELINES.txt

Full commit
Unit tests
==========

* Discuss Django and other unit tests available.

Document structure
====================

Single page document:

    *   Sphinx requires even a 1-HTML page document to be in at least two RST
        files.due to the requirement that the ``master_doc`` must include a
        ``toctree`` directive.  You can `read more about it here
        <http://sphinx.pocoo.org/latest/tutorial.html>`_.

    *   If your ``master_doc`` is called ``contents.rst``, then at a minimum it
        should contain something like:

    ::

        .. toctree::

           documentation

    *   And your other RST file is called, ``documentation.rst``, using the
        example above.  It can be anything, but do not call it ``index.rst``
        ``genindex``, ``modindex``, or ``search``.

Notes on splitting
===================

* Any file with a toctree directive in it cannot be commented on, especially if
    the toctree entry expands into multiple lines.  Maybe we can fix this later.
    But for now its not that big of a deal.

* If you use the `` `` directives at the start of a file that is split, then
    these replacements will only take place in the first split.  The remedy is
    to add all replacements in your ``conf.py`` file.  For example:

    ::

        rst_epilog = """
        .. |x| replace:: :math:`\mathrm{x}`
        .. |y| replace:: :math:`\mathrm{y}`
        """


==================
* Always start tables with the table directive

    NOT ADVISED
    -----------

    The HTML output will look OK, but the ucomment will
    not be added to the correct location.

    .. tabularcolumns:: |l|lllllllll|

    ==========   === === === === === === === === ===
    **Case A**   254 440 501 368 697 476 188 525
    ----------   --- --- --- --- --- --- --- --- ---
    **Case B**   338 470 558 426 733 539 240 628 517
    ==========   === === === === === === === === ===


    REQUIRED
    --------

    .. tabularcolumns:: |l|lllllllll|

    .. table::

    ==========   === === === === === === === === ===
    **Case A**   254 440 501 368 697 476 188 525
    ----------   --- --- --- --- --- --- --- --- ---
    **Case B**   338 470 558 426 733 539 240 628 517
    ==========   === === === === === === === === ===