python_packaging/documentation/conf.py

   1 #
   2 # This file is part of the GROMACS molecular simulation package.
   3 #
   4 # Copyright (c) 2015,2016,2017,2018,2019,2020, by the GROMACS development team, led by
   5 # Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
   6 # and including many others, as listed in the AUTHORS file in the
   7 # top-level source directory and at http://www.gromacs.org.
   8 #
   9 # GROMACS is free software; you can redistribute it and/or
  10 # modify it under the terms of the GNU Lesser General Public License
  11 # as published by the Free Software Foundation; either version 2.1
  12 # of the License, or (at your option) any later version.
  13 #
  14 # GROMACS is distributed in the hope that it will be useful,
  15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  17 # Lesser General Public License for more details.
  18 #
  19 # You should have received a copy of the GNU Lesser General Public
  20 # License along with GROMACS; if not, see
  21 # http://www.gnu.org/licenses, or write to the Free Software Foundation,
  22 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  23 #
  24 # If you want to redistribute modifications to GROMACS, please
  25 # consider that scientific software is very special. Version
  26 # control is crucial - bugs must be traceable. We will be happy to
  27 # consider code for inclusion in the official distribution, but
  28 # derived work must not be called official GROMACS. Details are found
  29 # in the README & COPYING files - if they are missing, get the
  30 # official version at http://www.gromacs.org.
  31 #
  32 # To help us fund GROMACS development, we humbly ask that you cite
  33 # the research papers on the package. Check out http://www.gromacs.org.
  34
  35 # Configuration file for the Sphinx documentation builder.
  36 #
  37 # This file only contains a selection of the most common options. For a full
  38 # list see the documentation:
  39 # http://www.sphinx-doc.org/en/master/config
  40
  41 from pkg_resources import get_distribution, DistributionNotFound
  42
  43 # -- General configuration ---------------------------------------------------
  44
  45 # Add any Sphinx extension module names here, as strings. They can be
  46 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
  47 # ones.
  48 extensions = [
  49     'sphinx.ext.autodoc',
  50     'sphinx.ext.autosummary',
  51     'sphinx.ext.coverage',
  52     'sphinx.ext.doctest',
  53     'sphinx.ext.intersphinx',
  54     'sphinx.ext.mathjax',
  55     'sphinx.ext.napoleon',
  56     'sphinx.ext.todo',
  57     'sphinx.ext.viewcode',
  58     'sphinxcontrib.plantuml'
  59 ]
  60
  61 # The master toctree document.
  62 master_doc = 'index'
  63
  64 # General information about the project.
  65 project = u'GROMACS scripting and extension API'
  66 copyright = u'2017, M. Eric Irrgang and Peter Kasson; 2019, GROMACS development team'
  67
  68 # The version info for the project you're documenting, acts as replacement for
  69 # |version| and |release|, also used in various other places throughout the
  70 # built documents.
  71 #
  72 # The short X.Y version.
  73 try:
  74     release = str(get_distribution('gmxapi').version)
  75     version = '.'.join(release.split('.')[:2])
  76 except DistributionNotFound:
  77     # package is not installed
  78     pass
  79
  80 # The language for content autogenerated by Sphinx. Refer to documentation
  81 # for a list of supported languages.
  82 #
  83 # This is also used if you do content translation via gettext catalogs.
  84 # Usually you set "language" from the command line for these cases.
  85 language = None
  86
  87 # List of patterns, relative to source directory, that match files and
  88 # directories to ignore when looking for source files.
  89 # This pattern also affects html_static_path and html_extra_path.
  90 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
  91
  92 # The reST default role (used for this markup: `text`) to use for all
  93 # documents.
  94 default_role = 'any'
  95
  96 # The name of the Pygments (syntax highlighting) style to use.
  97 pygments_style = 'sphinx'
  98
  99 # -- Options for todo extension ----------------------------------------------
 100
 101 # If true, `todo` and `todoList` produce output, else they produce nothing.
 102 todo_include_todos = True
 103
 104 # -- Options for HTML output -------------------------------------------------
 105
 106 # The theme to use for HTML and HTML Help pages.  See the documentation for
 107 # a list of builtin themes.
 108 #
 109 # GROMACS uses the 'classic' theme.
 110 html_theme = 'classic'
 111
 112 # The name for this set of Sphinx documents.
 113 # "<project> v<release> documentation" by default.
 114 #
 115 html_title = u'GROMACS External Interfaces'
 116
 117 # A shorter title for the navigation bar.  Default is the same as html_title.
 118 #
 119 html_short_title = u'gmxapi'
 120
 121 # Output file base name for HTML help builder.
 122 htmlhelp_basename = 'gmxapi'
 123
 124 # -- Options for Intersphinx -------------------------------------------------
 125
 126 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 127
 128 # -- Options for autodoc extension -------------------------------------------
 129 # reference https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
 130
 131 # Functions imported from C modules cannot be introspected, and therefore the
 132 # signature for such functions cannot be automatically determined. However, it is
 133 # an often-used convention to put the signature into the first line of the
 134 # function's docstring.
 135 #
 136 # If this boolean value is set to True (which is the default), autodoc will look
 137 # at the first line of the docstring for functions and methods, and if it looks
 138 # like a signature, use the line as the signature and remove it from the docstring
 139 # content.
 140 #
 141 autodoc_docstring_signature = True
 142
 143 # autodoc_mock_imports This value contains a list of modules to be mocked up. This
 144 # is useful when some external dependencies are not met at build time and break
 145 # the building process.
 146 #
 147 # New in version 1.3.
 148 #
 149 autodoc_mock_imports = []
 150
 151 # See http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autoclass_content
 152 autoclass_content = 'both'
 153
 154 # -- Options for Napoleon extension ------------------------------------------
 155 # reference https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#configuration
 156
 157 # -- Options for plantuml extension ------------------------------------------
 158
 159 plantuml = '/usr/bin/plantuml'