# ucommentapp-maintained / GUIDELINES.txt

  1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 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 _. * 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 ========== === === === === === === === === ===