doc/sphinx/index.rst

   1 .. SCons documentation master file, originally created by
   2    sphinx-quickstart on Mon Apr 30 09:36:53 2018.
   3    You can adapt this file completely to your liking, but it should at least
   4    contain the root `toctree` directive.
   5
   6 SCons API Documentation
   7 =======================
   8
   9 .. Attention::
  10    This is the **internal** API Documentation for SCons (aka
  11    "everything"). It is generated automatically from code docstrings using
  12    the `Sphinx <https://www.sphinx-doc.org>`_ documentation generator.
  13
  14    Any missing/incomplete information is due to shortcomings in the
  15    docstrings in the code. To not be too flippant about it, filling
  16    in all the docstrings has not always been a priority across the
  17    two-plus decades SCons has been in existence (contributions on this
  18    front are welcomed).  Additionally, for SCons classes which inherit
  19    from Python standard library classes (such as ``UserList``,
  20    ``UserDict``, ``UserString``), the generated pages will show methods
  21    that are inherited, sometimes with no information at all, sometimes
  22    with a signature/description that seems mangled: Python upstream has
  23    similar limitations as to the quality of dosctrings vs the current
  24    standards Sphinx expects.  Inherited interfaces from outside SCons
  25    code can be identified by the lack of a ``[source]`` button to the
  26    right of the method signature.
  27
  28    If you are looking for the Public API - the interfaces that have
  29    long-term consistency guarantees, which you can reliably use when
  30    writing a build system for a project - see the `SCons Reference Manual
  31    <https://scons.org/doc/production/HTML/scons-man.html>`_.  Note that
  32    what is Public API and what is not is not clearly delineated in these
  33    API Docs.
  34
  35    The target audience is both developers contributing to SCons itself,
  36    and those writing external Tools, Builders, and other related
  37    functionality for their project, who may need to reach beyond the
  38    Public API to accomplish their tasks. Reaching into internals is fine,
  39    but comes with the usual risks of "things here could change, it's up
  40    to you to keep your code working".
  41
  42
  43 .. toctree::
  44    :maxdepth: 2
  45    :caption: Contents:
  46
  47    SCons
  48    SCons.compat
  49    SCons.Node
  50    SCons.Platform
  51    SCons.Scanner
  52    SCons.Script
  53    SCons.Taskmaster
  54    SCons.Tool
  55    SCons.Util
  56    SCons.Variables
  57
  58
  59 Indices and Tables
  60 ==================
  61
  62 * :ref:`genindex`
  63 * :ref:`modindex`
  64 * :ref:`search`