Skip to content

Commit

Permalink
Adjusted documentation configuration.
Browse files Browse the repository at this point in the history
  • Loading branch information
@Paebbels
Paebbels committed Nov 9, 2021
1 parent 7f7695e commit dd7ba83
Showing 1 changed file with 181 additions and 53 deletions.
234 changes: 181 additions & 53 deletions doc/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,33 +10,170 @@
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('..'))
#sys.path.insert(0, os.path.abspath('../pyCallBy'))
#sys.path.insert(0, os.path.abspath('_extensions'))
#sys.path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme'))
from os.path import abspath
from pathlib import Path
from json import loads

sys.path.insert(0, abspath('.'))
sys.path.insert(0, abspath('..'))
sys.path.insert(0, abspath('../pyTooling.TerminalUI'))
sys.path.insert(0, abspath('_extensions'))
#sys.path.insert(0, os.path.abspath('_themes/sphinx_rtd_theme'))

# -- Project information -----------------------------------------------------

# ==============================================================================
# Project information
# ==============================================================================
project = 'pyTooling.TerminalUI'
copyright = '2007-2021, Patrick Lehmann'
author = 'Patrick Lehmann'

# ==============================================================================
# Versioning
# ==============================================================================
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
from subprocess import check_output

def _IsUnderGitControl():
return (check_output(["git", "rev-parse", "--is-inside-work-tree"], universal_newlines=True).strip() == "true")

def _LatestTagName():
return check_output(["git", "describe", "--abbrev=0", "--tags"], universal_newlines=True).strip()

# The full version, including alpha/beta/rc tags
release = 'v1.5'
version = "1.5" # The short X.Y version.
release = "1.5.1" # The full version, including alpha/beta/rc tags.
try:
if _IsUnderGitControl:
latestTagName = _LatestTagName()[1:] # remove prefix "v"
versionParts = latestTagName.split("-")[0].split(".")

version = ".".join(versionParts[:2])
release = latestTagName # ".".join(versionParts[:3])
except:
pass

# ==============================================================================
# Miscellaneous settings
# ==============================================================================
# The master toctree document.
master_doc = 'index'

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [
"_build",
"_themes",
"Thumbs.db",
".DS_Store"
]

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'stata-dark'


# ==============================================================================
# Restructured Text settings
# ==============================================================================
prologPath = "prolog.inc"
try:
with open(prologPath, "r") as prologFile:
rst_prolog = prologFile.read()
except Exception as ex:
print("[ERROR:] While reading '{0!s}'.".format(prologPath))
print(ex)
rst_prolog = ""


# ==============================================================================
# Options for HTML output
# ==============================================================================
html_theme_options = {
'home_breadcrumbs': True,
'vcs_pageview_mode': 'blob',
}

html_context = {}
ctx = Path(__file__).resolve().parent / 'context.json'
if ctx.is_file():
html_context.update(loads(ctx.open('r').read()))

html_theme_path = ["."]
html_theme = "_theme"

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Output file base name for HTML help builder.
htmlhelp_basename = 'pyToolingDoc'

# If not None, a 'Last updated on:' timestamp is inserted at every page
# bottom, using the given strftime format.
# The empty string is equivalent to '%b %d, %Y'.
html_last_updated_fmt = "%d.%m.%Y"

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
# ==============================================================================
# Options for LaTeX / PDF output
# ==============================================================================
from textwrap import dedent

latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',

# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',

# Additional stuff for the LaTeX preamble.
'preamble': dedent(r"""
% ================================================================================
% User defined additional preamble code
% ================================================================================
% Add more Unicode characters for pdfLaTeX.
% - Alternatively, compile with XeLaTeX or LuaLaTeX.
% - https://github.com/sphinx-doc/sphinx/issues/3511
%
\ifdefined\DeclareUnicodeCharacter
\DeclareUnicodeCharacter{2265}{$\geq$}
\DeclareUnicodeCharacter{21D2}{$\Rightarrow$}
\fi
% ================================================================================
"""),

# Latex figure (float) alignment
#'figure_align': 'htbp',
}

# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
( master_doc,
'pyTooling.TerminalUI.tex',
'The pyTooling.TerminalUI Documentation',
'Patrick Lehmann',
'manual'
),
]



# ==============================================================================
# Extensions
# ==============================================================================
extensions = [
# Sphinx theme
"sphinx_rtd_theme",
# Standard Sphinx extensions
"sphinx.ext.autodoc",
'sphinx.ext.extlinks',
Expand All @@ -47,57 +184,39 @@
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
# 'sphinx.ext.duration',
# 'sphinx.ext.duration',

# SphinxContrib extensions
# SphinxContrib extensions
# 'sphinxcontrib.actdiag',
'sphinxcontrib.mermaid',
# 'sphinxcontrib.seqdiag',
# 'sphinxcontrib.textstyle',
# 'sphinxcontrib.spelling',
# 'changelog',

# BuildTheDocs extensions
'btd.sphinx.autoprogram',
# BuildTheDocs extensions
# 'btd.sphinx.autoprogram',
# 'btd.sphinx.graphviz',
# 'btd.sphinx.inheritance_diagram',

# Other extensions
# 'DocumentMember',
# Other extensions
# 'DocumentMember',
'sphinx_fontawesome',
'sphinx_autodoc_typehints',

# local extensions (patched)
# local extensions (patched)
# 'autoapi.sphinx',

# local extensions
# 'DocumentMember'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = [
"_build",
"Thumbs.db",
".DS_Store"
]


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
# html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# ==============================================================================
# Sphinx.Ext.InterSphinx
# ==============================================================================
intersphinx_mapping = {
'python': ('https://docs.python.org/3', None),
'pyTooling': ('http://pyTooling.github.io/pyTooling', None),
'python': ('https://docs.python.org/3', None),
'pyTooling': ('http://pyTooling.github.io/pyTooling', None),
}


Expand All @@ -112,10 +231,10 @@
# Sphinx.Ext.ExtLinks
# ==============================================================================
extlinks = {
'issue': ('https://github.com/pyTooling/pyTooling,TerminalUI/issues/%s', 'issue #'),
'pull': ('https://github.com/pyTooling/pyTooling,TerminalUI/pull/%s', 'pull request #'),
'src': ('https://github.com/pyTooling/pyTooling,TerminalUI/blob/master/pyTooling,TerminalUI/%s?ts=2', None),
# 'tests': ('https://github.com/pyTooling/pyCallBy/blob/master/test/%s?ts=2', None)
'issue': ('https://github.com/pyTooling/pyTooling.TerminalUI/issues/%s', 'issue #'),
'pull': ('https://github.com/pyTooling/pyTooling.TerminalUI/pull/%s', 'pull request #'),
'src': ('https://github.com/pyTooling/pyTooling.TerminalUI/blob/master/pyTooling/%s?ts=2', None),
# 'test': ('https://github.com/pyTooling/pyTooling/blob/master/test/%s?ts=2', None)
}


Expand All @@ -132,3 +251,12 @@
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
todo_link_only = True



# ==============================================================================
# AutoAPI.Sphinx
# ==============================================================================
autoapi_modules = {
'pyTooling.TerminalUI': {'output': "pyTooling.TerminalUI", "override": True}
}

0 comments on commit dd7ba83

Please sign in to comment.