From 747182e88aa859afb93f9338d7beb025ea60c378 Mon Sep 17 00:00:00 2001 From: crocsg Date: Sun, 8 Oct 2023 18:54:51 +0200 Subject: [PATCH] restore old sphynx conf.py --- docs/conf.py | 259 ++++++++++++----------------------------------- docs/conf.py.rtd | 217 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 282 insertions(+), 194 deletions(-) create mode 100644 docs/conf.py.rtd diff --git a/docs/conf.py b/docs/conf.py index 5022a93..eea7df2 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,217 +1,88 @@ # -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/stable/config -# -- Path setup -------------------------------------------------------------- +from __future__ import division, print_function, unicode_literals -# If extensions (or modules to document with autodoc) are in another directory, -# 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('.')) -import logging -import os.path -import re -import subprocess +import os +import sys + +#import sphinx_rtd_theme +from recommonmark.parser import CommonMarkParser + +sys.path.insert(0, os.path.abspath('..')) +sys.path.append(os.path.dirname(__file__)) +os.environ.setdefault("DJANGO_SETTINGS_MODULE", "readthedocs.settings.dev") -logger = logging.getLogger('rtd-samples') - -def get_git_branch(): - """Get the git branch this repository is currently on""" - path_to_here = os.path.abspath(os.path.dirname(__file__)) - - # Invoke git to get the current branch which we use to get the theme - try: - p = subprocess.Popen(['git', 'branch'], stdout=subprocess.PIPE, cwd=path_to_here) - - # This will contain something like "* (HEAD detached at origin/MYBRANCH)" - # or something like "* MYBRANCH" - branch_output = p.communicate()[0] - - # This is if git is in a normal branch state - match = re.search(r'\* (?P[^\(\)\n ]+)', branch_output) - if match: - return match.groupdict()['branch_name'] - - # git is in a detached HEAD state - match = re.search(r'\(HEAD detached at origin/(?P[^\)]+)\)', branch_output) - if match: - return match.groupdict()['branch_name'] - except Exception: - logger.exception(u'Could not get the branch') - - # Couldn't figure out the branch probably due to an error - return None - - -# -- Project information ----------------------------------------------------- - -project = u'BrailleRAP' -copyright = u'CERN licence V1.2' -author = u'BrailleRAP team' - -# The short X.Y version -version = u'6.5' -# The full version, including alpha/beta/rc tags -release = u'6.5' - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. +sys.path.append(os.path.abspath('_ext')) extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.autosectionlabel', + 'sphinx_rtd_theme', + ] - -# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ['.rst', '.md'] +source_parsers = { + '.md': CommonMarkParser, +} -# The master toctree document. master_doc = 'index' +project = u'BrailleRap' +copyright = '2018-{}, BrailleRap' -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = 'fr' - -# 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 = [u'_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. +version = '6.5.0' +release = '6.5.0' +exclude_patterns = ['_build'] +default_role = 'obj' pygments_style = 'sphinx' - -# -- Options for HTML output ------------------------------------------------- - -# Maps git branches to Sphinx themes -default_html_theme = 'sphinx_rtd_theme' -branch_to_theme_mapping = { - # 3rd party themes - 'master': default_html_theme, - - # Sphinx built-in themes - 'alabaster': 'alabaster', - 'classic': 'classic', - 'sphinxdoc': 'sphinxdoc', - 'scrolls': 'scrolls', - 'agogo': 'agogo', - 'traditional': 'traditional', - 'nature': 'nature', - 'haiku': 'haiku', - 'pyramid': 'pyramid', - 'bizstyle': 'bizstyle', -} -current_branch = None #get_git_branch() - -if current_branch: - sphinx_html_theme = branch_to_theme_mapping.get(current_branch, default_html_theme) - print(u'Got theme {} from branch {}'.format(sphinx_html_theme, current_branch)) -else: - sphinx_html_theme = default_html_theme - print(u'Error getting current branch - using default theme') - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = sphinx_html_theme - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# 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'] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = 'BrailleRAPdoc' - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # 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]). +#intersphinx_mapping = { +# 'python': ('http://python.readthedocs.io/en/latest/', None), +# 'django': ('http://django.readthedocs.io/en/1.8.x/', None), +# 'sphinx': ('http://sphinx.readthedocs.io/en/latest/', None), +#} +htmlhelp_basename = 'BrailleRapdoc' latex_documents = [ - (master_doc, 'BrailleRAP.tex', project, - u'BrailleRAP team', 'manual'), + ('index', 'BrailleRap.tex', u'BrailleRap Documentation', + u'BrailleRap Team', 'manual'), ] +#man_pages = [ +# ('index', 'read-the-docs', u'Read the Docs Documentation', +# [u'Eric Holscher, Charlie Leifer, Bobby Grace'], 1) +#] -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'BrailleRAPman', project, - [author], 1) +exclude_patterns = [ + # 'api' # needed for ``make gettext`` to not die. ] +language = 'fr' -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'BrailleRAPtexinfo', project, - author, 'BrailleRAPtexinfo', 'Open source DIY Braille embosser.', - 'Miscellaneous'), +locale_dirs = [ + 'locale/', ] +gettext_compact = False +gettext_uuid = False + +html_theme = 'sphinx_rtd_theme' +#html_static_path = ['_static'] +#html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +#html_theme_path = ["_themes"] +#html_logo = 'IMG/logo.svg' + +html_theme_options = { + 'logo_only': False, + 'display_version': True, +} + + +def setup(app): + #app.add_stylesheet('css/custom.css') + app.add_css_file('css/custom.css') + pass + + + diff --git a/docs/conf.py.rtd b/docs/conf.py.rtd new file mode 100644 index 0000000..5022a93 --- /dev/null +++ b/docs/conf.py.rtd @@ -0,0 +1,217 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/stable/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# 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('.')) +import logging +import os.path +import re +import subprocess + + +logger = logging.getLogger('rtd-samples') + + +def get_git_branch(): + """Get the git branch this repository is currently on""" + path_to_here = os.path.abspath(os.path.dirname(__file__)) + + # Invoke git to get the current branch which we use to get the theme + try: + p = subprocess.Popen(['git', 'branch'], stdout=subprocess.PIPE, cwd=path_to_here) + + # This will contain something like "* (HEAD detached at origin/MYBRANCH)" + # or something like "* MYBRANCH" + branch_output = p.communicate()[0] + + # This is if git is in a normal branch state + match = re.search(r'\* (?P[^\(\)\n ]+)', branch_output) + if match: + return match.groupdict()['branch_name'] + + # git is in a detached HEAD state + match = re.search(r'\(HEAD detached at origin/(?P[^\)]+)\)', branch_output) + if match: + return match.groupdict()['branch_name'] + except Exception: + logger.exception(u'Could not get the branch') + + # Couldn't figure out the branch probably due to an error + return None + + +# -- Project information ----------------------------------------------------- + +project = u'BrailleRAP' +copyright = u'CERN licence V1.2' +author = u'BrailleRAP team' + +# The short X.Y version +version = u'6.5' +# The full version, including alpha/beta/rc tags +release = u'6.5' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'fr' + +# 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 = [u'_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for HTML output ------------------------------------------------- + +# Maps git branches to Sphinx themes +default_html_theme = 'sphinx_rtd_theme' +branch_to_theme_mapping = { + # 3rd party themes + 'master': default_html_theme, + + # Sphinx built-in themes + 'alabaster': 'alabaster', + 'classic': 'classic', + 'sphinxdoc': 'sphinxdoc', + 'scrolls': 'scrolls', + 'agogo': 'agogo', + 'traditional': 'traditional', + 'nature': 'nature', + 'haiku': 'haiku', + 'pyramid': 'pyramid', + 'bizstyle': 'bizstyle', +} +current_branch = None #get_git_branch() + +if current_branch: + sphinx_html_theme = branch_to_theme_mapping.get(current_branch, default_html_theme) + print(u'Got theme {} from branch {}'.format(sphinx_html_theme, current_branch)) +else: + sphinx_html_theme = default_html_theme + print(u'Error getting current branch - using default theme') + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = sphinx_html_theme + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# 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'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'BrailleRAPdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # 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, 'BrailleRAP.tex', project, + u'BrailleRAP team', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'BrailleRAPman', project, + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'BrailleRAPtexinfo', project, + author, 'BrailleRAPtexinfo', 'Open source DIY Braille embosser.', + 'Miscellaneous'), +]