python_packaging/documentation/conf.py

   1 # Configuration file for the Sphinx documentation builder.
   2 #
   3 # This file only contains a selection of the most common options. For a full
   4 # list see the documentation:
   5 # http://www.sphinx-doc.org/en/master/config
   6
   7 from pkg_resources import get_distribution, DistributionNotFound
   8
   9 # -- General configuration ---------------------------------------------------
  10
  11 # Add any Sphinx extension module names here, as strings. They can be
  12 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
  13 # ones.
  14 extensions = [
  15     'sphinx.ext.autodoc',
  16     'sphinx.ext.autosummary',
  17     'sphinx.ext.coverage',
  18     'sphinx.ext.doctest',
  19     'sphinx.ext.intersphinx',
  20     'sphinx.ext.mathjax',
  21     'sphinx.ext.napoleon',
  22     'sphinx.ext.todo',
  23     'sphinx.ext.viewcode',
  24     'sphinxcontrib.plantuml'
  25 ]
  26
  27 # The master toctree document.
  28 master_doc = 'index'
  29
  30 # General information about the project.
  31 project = u'GROMACS scripting and extension API'
  32 copyright = u'2017, M. Eric Irrgang and Peter Kasson; 2019, GROMACS development team'
  33
  34 # The version info for the project you're documenting, acts as replacement for
  35 # |version| and |release|, also used in various other places throughout the
  36 # built documents.
  37 #
  38 # The short X.Y version.
  39 try:
  40     release = str(get_distribution('gmxapi').version)
  41     version = '.'.join(release.split('.')[:2])
  42 except DistributionNotFound:
  43     # package is not installed
  44     pass
  45
  46 # The language for content autogenerated by Sphinx. Refer to documentation
  47 # for a list of supported languages.
  48 #
  49 # This is also used if you do content translation via gettext catalogs.
  50 # Usually you set "language" from the command line for these cases.
  51 language = None
  52
  53 # List of patterns, relative to source directory, that match files and
  54 # directories to ignore when looking for source files.
  55 # This pattern also affects html_static_path and html_extra_path.
  56 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
  57
  58 # The name of the Pygments (syntax highlighting) style to use.
  59 pygments_style = 'sphinx'
  60
  61 # -- Options for todo extension ----------------------------------------------
  62
  63 # If true, `todo` and `todoList` produce output, else they produce nothing.
  64 todo_include_todos = True
  65
  66 # -- Options for HTML output -------------------------------------------------
  67
  68 # The theme to use for HTML and HTML Help pages.  See the documentation for
  69 # a list of builtin themes.
  70 #
  71 # GROMACS uses the 'classic' theme.
  72 html_theme = 'classic'
  73
  74 # The name for this set of Sphinx documents.
  75 # "<project> v<release> documentation" by default.
  76 #
  77 html_title = u'GROMACS External Interfaces'
  78
  79 # A shorter title for the navigation bar.  Default is the same as html_title.
  80 #
  81 html_short_title = u'gmxapi'
  82
  83 # Output file base name for HTML help builder.
  84 htmlhelp_basename = 'gmxapi'
  85
  86 # -- Options for Intersphinx -------------------------------------------------
  87
  88 intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
  89
  90 # -- Options for autodoc extension -------------------------------------------
  91 # reference https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
  92
  93 # Functions imported from C modules cannot be introspected, and therefore the
  94 # signature for such functions cannot be automatically determined. However, it is
  95 # an often-used convention to put the signature into the first line of the
  96 # function's docstring.
  97 #
  98 # If this boolean value is set to True (which is the default), autodoc will look
  99 # at the first line of the docstring for functions and methods, and if it looks
 100 # like a signature, use the line as the signature and remove it from the docstring
 101 # content.
 102 #
 103 autodoc_docstring_signature = True
 104
 105 # autodoc_mock_imports This value contains a list of modules to be mocked up. This
 106 # is useful when some external dependencies are not met at build time and break
 107 # the building process.
 108 #
 109 # New in version 1.3.
 110 #
 111 autodoc_mock_imports = []
 112
 113 # See http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autoclass_content
 114 autoclass_content = 'both'
 115
 116 # -- Options for Napoleon extension ------------------------------------------
 117 # reference https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#configuration
 118
 119 # -- Options for plantuml extension ------------------------------------------
 120
 121 plantuml = '/usr/bin/plantuml'