Line data    Source code

       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : # Writing Good Documentation {#writing_good_dox}
       6             : 
       7             : \tableofcontents
       8             : 
       9             : # Tutorials, Instructions, and Dev Guide {#writing_dox_writing_help}
      10             : 
      11             : All non-code documentation such as tutorials, installation instructions, and
      12             : the developer guide is written inside Markdown files such as this one. These
      13             : files must be placed inside `docs/Tutorials`, `docs/MainSite`, or
      14             : `docs/DevGuide` according to what they document. Each Markdown file must start
      15             : with the following line
      16             : 
      17             : ``` markdown
      18             : # The title {#the_tag}
      19             : ```
      20             : 
      21             : where `The title` is replaced with your desired title, and `the_tag` with the
      22             : tag you want to use to reference the Markdown file and documentation. Each
      23             : main heading of the file starts with a single octothorpe
      24             : and can have a tag. For example,
      25             : 
      26             : ``` markdown
      27             : # My Section {#file_name_my_section}
      28             : ```
      29             : 
      30             : While the `file_name` portion is not necessary, it is useful for reducing the
      31             : likelihood of reference collisions. You can add a table of contents using the
      32             : Doxygen command <code>\\tableofcontents</code>. All sections, subsections,
      33             : subsubsections, etc. are shown in the table of contents if they have a tag,
      34             : if not they do not appear.
      35             : 
      36             : # C++ Documentation {#writing_dox_cpp_dox_help}
      37             : 
      38             : We require you to add Doxygen documentation for any of the following
      39             : you may have added to the public interface in any hpp file:
      40             : 
      41             : + classes
      42             : + structs
      43             : + enums
      44             : + functions
      45             : + namespaces
      46             : + macros
      47             : + type aliases
      48             : 
      49             : Documentation begins on the line immediately above the declaration with
      50             : either a triple slash `///` or a `/*!`.
      51             : 
      52             : Examples:
      53             : \verbatim
      54             : /// A brief description of the object to be documented
      55             : ///
      56             : /// Doxygen comments can be made
      57             : /// using triple slashes...
      58             : class ExampleClass{
      59             :   ... rest of code
      60             : }
      61             : \endverbatim
      62             : 
      63             : \verbatim
      64             : /*!
      65             :  * \brief A brief description of the object to be documented
      66             :  *
      67             :  * Doxygen comments can also be made
      68             :  * using the "slash-star, star-slash" pattern, in this way.
      69             :  */
      70             : class ExampleClass{
      71             :   ... rest of code
      72             : }
      73             : \endverbatim
      74             : 
      75             : Build your documentation by running `make doc` in your build directory.
      76             : You can then view it by opening `BUILD_DIR/docs/html/index.html` in a
      77             : browser and using the file navigator in Doxygen to locate your file.
      78             : 
      79             : In addition to providing a file directory of all the source files in SpECTRE,
      80             : Doxygen also conveniently provides two additional organizations of the files,
      81             : Modules and Namespaces. To ensure that your documentation is easily found from
      82             : within Doxygen, we recommend that you add any new objects to Modules and any
      83             : new namespaces to Namespaces.
      84             : 
      85             : \note The `///` Doxygen syntax does not require a `\brief`, while the C-style
      86             : `/*!` does.
      87             : 
      88             : ## Add your object to an existing Module:
      89             : 
      90             : Within a Doxygen comment, use the Doxygen keyword
      91             : \verbatim
      92             : \ingroup
      93             : \endverbatim
      94             : 
      95             : followed by the name of the Module (you can find the list of existing Modules in
      96             : `docs/GroupDefs.hpp`).
      97             : 
      98             : ## Add a new Module:
      99             : 
     100             : Within `docs/GroupDefs.hpp`, add the name of your Module (which follows the
     101             : naming convention "YourNameForModule" followed by "Group") among the rest,
     102             : taking care to keep the list of Modules in alphabetical order.
     103             : 
     104             : ## Add a new namespace:
     105             : 
     106             : In the hpp file in which the namespace is declared for the first time,
     107             : add a Doxygen comment to the line directly above the namespace. Subsequent
     108             : files which use this namespace will not need a Doxygen comment.
     109             : 
     110             : We also strongly encourage you to:
     111             : 
     112             : ## Put any mathematical expressions in your documentation into LaTeX form:
     113             : 
     114             : Within a Doxygen comment, begin and conclude your expression with
     115             : 
     116             : \verbatim
     117             : \f$
     118             : \endverbatim
     119             : 
     120             : Example:
     121             : \verbatim
     122             : \\\ We define \f$ \xi : = \eta^2 \f$
     123             : \endverbatim
     124             : 
     125             : Note that if this expression spans more than one line,
     126             : your Doxygen comment must of the "slash-star, star-slash" form shown in the
     127             : previous section. One can also use (within a Doxygen comment) the form
     128             : 
     129             : \verbatim
     130             : \f[ expression \f]
     131             : \endverbatim
     132             : 
     133             : to put the expression on its own line. We also encourage you to use the latex
     134             : env `align` for formatting these multiple-line equations. Please prefer the
     135             : `align` environment over the `eqnarray` environment. See the
     136             : [texfaq](https://texfaq.org/FAQ-eqnarray) for an explanation as to why. When
     137             : using out-of-line equations it is important to have a blank Doxygen line above
     138             : and below the equation so that ClangFormat does not merge the equation with
     139             : other lines. For example,
     140             : 
     141             : \verbatim
     142             :  * word word word
     143             :  *
     144             :  * \f{align}{
     145             :  *   a &= b \\
     146             :  *   c &= d
     147             :  * \f}
     148             :  *
     149             :  * word word word
     150             : \endverbatim
     151             : 
     152             : prevents ClangFormat from changing the code to
     153             : 
     154             : \verbatim
     155             : word word word \f{align}{ a &= b \\ c &= d \f}
     156             : \endverbatim
     157             : 
     158             : which may not render properly and makes the source code harder to read.
     159             : 
     160             : ## Cite publications in your documentation {#writing_dox_citations}
     161             : 
     162             : When you refer to publications or books in the documentation, add a
     163             : corresponding entry to `docs/References.bib`. Follow these guidelines when
     164             : editing `docs/References.bib`:
     165             : 
     166             : - Ideally, find the publication on [INSPIRE HEP](https://inspirehep.net) and
     167             : copy its BibTeX entry.
     168             : - For publications that are not listed on [INSPIRE HEP](https://inspirehep.net),
     169             : make sure to format the new entry's key in the same style, i.e.
     170             : `(<Author>[a-zA-Z]+):(<Year>[0-9]{4})(<ID>[a-z]*)`. Good keys are, for
     171             : instance, `Einstein:1915` or `LVC:2016a`. For books you may omit the year.
     172             : - Sort the list of BibTeX entries in the file alphabetically by their keys.
     173             : - Provide open access or preprint information whenever possible. For
     174             : publications available on [arXiv](https://arxiv.org), for instance, add the
     175             : following fields (filling in the correct values):
     176             : ```
     177             : archivePrefix = {arXiv},
     178             : eprint = {1609.00098},
     179             : primaryClass = {astro-ph.HE},
     180             : ```
     181             : - Provide the `url` field whenever possible. If a DOI has been issued by the
     182             : publisher, use `https://doi.org/<doi>` and also fill the `doi` field of the
     183             : entry. Else, use the URL provided by the publisher.
     184             : - Make sure to wrap strings in the BibTeX entries in `{}` when capitalization is
     185             : important, or when BibTeX keywords should be ignored (e.g. `and` in author
     186             : lists).
     187             : 
     188             : To cite an entry from the `docs/References.bib` file in the documentation, use
     189             : the Doxygen keyword
     190             : \verbatim
     191             : \cite
     192             : \endverbatim
     193             : followed by the BibTeX key at the place in the documentation where you want the
     194             : citation to appear. It will render as a numbered link to the bibliography
     195             : page. It will also show a popover when hovering over the link, which displays
     196             : the bibliographic information and provides quick access to the publication.
     197             : 
     198             : ## Include any pictures that aid in the understanding of your documentation:
     199             : 
     200             : First, please compress your image to be under 130kB. As most images will be
     201             : diagrammatical in nature this is certainly achievable!
     202             : 
     203             : Second, add the directory that will contain your image to the `docs/Images/`
     204             : directory. Create the appropriate directories such that the directory structure
     205             : in `docs/Images` matches that of `src` and `tests/Unit`.
     206             : 
     207             : Finally, include the image by using the Doxygen keyword
     208             : 
     209             : \verbatim
     210             : \image html NameOfImage.png
     211             : \endverbatim
     212             : 
     213             : in your hpp file.
     214             : 
     215             : # Python Documentation {#writing_dox_python_dox_help}
     216             : 
     217             : DocStrings...