docs/dev-manual/index.rst

   1 .. _dev guide:
   2
   3 ***************
   4 Developer Guide
   5 ***************
   6
   7 .. highlight:: bash
   8
   9 This set of pages contains guidelines, instructions, and explanations related
  10 to |Gromacs| development.  The actual code is documented in Doxygen
  11 documentation linked below.
  12
  13 The focus is (at least for now) on things that are tightly tied to the code
  14 itself, such as helper scripts that reside in the source repository and
  15 organization of the code itself, and may require the documentation to be
  16 updated in sync.
  17
  18 The guide is currently split into a few main parts:
  19
  20 * Overview of the |Gromacs| codebase.
  21 * Collection of overview pages that describe some important implementation
  22   aspects.
  23 * Generic guidelines to follow when developing |Gromacs|.
  24   For some of the guidelines, scripts exist (see below) to automatically
  25   reformat the code and/or enforce the guidelines for each commit.
  26 * Instructions on what tools are used, and how to use them.
  27
  28 .. only:: html
  29
  30         In addition to this, Doxygen documentation extracted from the comments
  31         in the C/C++ code is available to document the actual existing code.
  32
  33 .. only:: latex
  34
  35         **The full code documentation generated from Doxygen can be found in the online
  36         documentation. It is not included here in order to save the trees.**
  37
  38 Some overview documentation that is closely related to the actual C/C++ code
  39 appears in the Doxygen documentation, while some other overview content is in
  40 the developer guide.  The reasons are partially technical, but crosslinks
  41 between the developer guide and the Doxygen documentation are provided whenever
  42 related content appears split between the two sources.
  43
  44 The documentation does not yet cover all areas, but more content is being
  45 (slowly) added.
  46 Wiki pages at http://www.gromacs.org/Developer_Zone may contain additional
  47 information (much of it outdated, though), and can be linked from relevant
  48 locations in the developer guide.
  49
  50 .. toctree::
  51    :maxdepth: 2
  52
  53    contribute
  54    overview
  55    build-system
  56    change-management
  57    relocatable-binaries
  58    documentation-generation
  59    style
  60    tools
  61
  62 *********************
  63 Doxygen documentation
  64 *********************
  65
  66 .. only:: html
  67
  68   * `Public API documentation <doxygen/html-user/index.xhtml>`_
  69        This contains documentation for code that appears in installed headers,
  70        as well as some overview documentation to understand those parts of the
  71        code.
  72        Please note that the definition of the public API is very preliminary
  73        and subject to change, in particular for parts that have not been
  74        documented.
  75   * `Code documentation <doxygen/html-lib/index.xhtml>`_
  76        This contains the public API documentation as a subset, but also has more
  77        details on the internal implementation of |Gromacs|.  This is a good
  78        place to start to understand some specific area of the code in general
  79        to, e.g., contribute.
  80   * `Full documentation <doxygen/html-full/index.xhtml>`_
  81        This contains every single documented function from the codebase,
  82        including internal  There can be an overwhelming amount of detail, but
  83        this can be useful if trying to find some specific function within the
  84        codebase.
  85
  86 .. only:: latex
  87
  88     The doxygen code documentation is available on the |Gromacs| webpage.
  89
  90