conf.py - Configuration file for this Sphinx CodeChat project

This file configures Sphinx, which transforms restructured text (reST) into html. See Sphinx build configuration file docs for more information on the settings below.

This file was originally created by sphinx-quickstart, then modified by hand. Notes on its operation:

  • This file is execfile()d by Sphinx with the current directory set to its containing dir.
  • Not all possible configuration values are present in this autogenerated file.
  • All configuration values have a default; values that are commented out serve to show the default.
import sys, os.path

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, as shown here.

sys.path.insert(0, os.path.abspath('build/Sphinx/ext'))

Scattered content

The configuration for several features is necessarily scattered throughout this file. This documentation combines these pieces.

Annotator

Annotator allows users to add annotations to a web page. Including Annotator requires:

  1. Copy Annotator JavaScript code to the _static directory.
  2. Including the Annotator script in each web page.
  3. Configure Annotator by adding a snippet of JavaScript at the end of each web page.

Interactive questions

See also Interactive questions.

  1. Copy interactive files to the _static directory.
  2. Include the feedback script and feedback CSS in each web page.
  3. Use custom directives to insert feedback elements.

jQuery

Both Annotator and the Interactive questions rely on jQuery. Sphinx v1.5.1 also uses it, so we don’t need to package it separately.

Project information

project and copyright: General information about the project. Change this for your project.

project = 'Learning assembly and C with the PIC24 family'
copyright = '2016, Bryan A. Jones'
 

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. Change these for your project.

version: The short X.Y version.

version = '0.0'

release: The full version, including alpha/beta/rc tags.

release = 'version 0.0'
 

highlight_language: The default language to highlight source code in.

highlight_language = 'c'
 

pygments_style: The style name to use for Pygments highlighting of source code.

pygments_style = 'sphinx'

General configuration

extensions: If your documentation needs a minimal Sphinx version, state it here. CodeChat note: CodeChat has been tested with Sphinx 1.3 and above. Older versions may or may not work.

needs_sphinx = '1.3'
 

Add any Sphinx extension module names here, as strings. They can be extensions coming with Sphinx (named ‘sphinx.ext.*’) or your custom ones. CodeChat note: The CodeChat.CodeToRestSphinx extension is mandatory; without it, CodeChat will not translate source code to reST and then (via Sphinx) to html.

extensions = [
    'sphinx.ext.mathjax',
    'sphinx.ext.graphviz',
    'SphinxBookExtension',
    'inlinesyntaxhighlight',
]
 

rst_prolog: A string of reStructuredText that will be included at the beginning of every source file that is read.

rst_prolog = (

Allow the display of Flask flash messages. Copied from flask-user’s templates. See http://flask.pocoo.org/docs/0.11/patterns/flashing/.

When this is viewed as a web page, it confuses Jinja2. So, tell it to ignore the following lines

##
"""
.. raw:: html

    {%- with messages = get_flashed_messages(with_categories=true) -%}
        {% if messages %}
            {% for category, message in messages %}
                {% if category=='error' %}
                    {% set category='danger' %}
                {% endif %}
                <div class="attention alert-{{category}}">{{ message|safe }}</div>
            {% endfor %}
        {% endif %}
    {%- endwith %}

"""
##
)
 

rst_epilog: A string of reStructuredText that will be included at the end of every source file that is read.

rst_epilog = (

See https://groups.google.com/forum/#!topic/sphinx-users/DDO07AA2w-c for the syntax used to make this work.

"""
.. |PIC24_family| replace:: `PIC24 family <http://www.microchip.com/design-centers/16-bit>`__

"""
 

Named external links; see References for a mapping to the names of these documents.

"""
.. _asmguide: http://ww1.microchip.com/downloads/en/DeviceDoc/51317G.pdf
.. _cguide: http://ww1.microchip.com/downloads/en/DeviceDoc/50002071E.pdf
.. _libref: http://ww1.microchip.com/downloads/en/DeviceDoc/50001456J.pdf

.. _pic24eds: http://courses.ece.msstate.edu/ece3724/main_pic24/datasheets/70000657H.pdf
.. _progref: http://courses.ece.msstate.edu/ece3724/main_pic24/datasheets/70157F.pdf

.. _frmcpu: http://courses.ece.msstate.edu/ece3724/main_pic24/datasheets/S2.pdf
.. _frmdatamem: http://courses.ece.msstate.edu/ece3724/main_pic24/datasheets/DS-70595C.pdf
.. _frmprogmem: http://courses.ece.msstate.edu/ece3724/main_pic24/datasheets/70613C.pdf

"""

Configure Annotator

This must be done at the end of the HTML, not the beginning; otherwise, Annotator produces errors.

"""
.. Since the backend isn't ready yet, comment this out for now.
    raw:: html

    <script type="text/javascript">
        var app = new annotator.App();
        app.include(annotator.ui.main);
        app.include(annotator.storage.http);
    </script>

    <p>
        <a href="javascript:enableAddComment();">Add a comment</a> |
        <a href="javascript:enableAskQuestion();">Ask a question</a> |
        <a href="javascript:enableReportProblem();">Report a problem</a>
    </p>

    <div id="comment_explanation" style="display: none;">
        You may now highlight a part of this web page then click on the icon that appears to <span id="comment_action"></span>
    </div>

"""
 

Provide a convenient way to refer to a source file’s name. See _docname_role.

""".. |docname| replace:: :docname:`name`
"""
 

Include common abbreviations. Use a raw string to avoid escaping the \ characters.

r""".. |I2C| replace:: I\ :sup:`2`\ C
.. |R/W| replace:: :math:`\textrm{R}/\overline{\textrm{W}}`
.. |ohm| unicode:: U+03A9 .. Greek capital omega
"""
)
 

default_role The name of a reST role (builtin or Sphinx extension) to use as the default role, that is, for text marked up `like this`.

See the :any: role, which suggests this use.

default_role = 'any'
 

source_suffix: The suffix of source filenames.

source_suffix = '.rst'
 

master_doc: The master toctree document.

master_doc = 'index'
 

language: The language for content autogenerated by Sphinx. Refer to documentation for a list of supported languages.

language = 'en'
 

exclude_patterns: List of patterns, relative to source directory, that match files and directories to ignore when looking for source files. CodeChat note: By default, Enki will instruct Sphinx to place all Sphinx output in _build; this directory should therefore be excluded from the list of source files.

exclude_patterns = [

Python temp files.

    '**__pycache__',

Sphinx output.

    '_build',

Git.

    '.git',

Enki/CodeChat files.

    'sphinx-enki-info.txt',

MPLAB X projects.

    '**.X',

PIC24 library.

    'lib',

Waf output.

    'build/waf/out',
    'waf*',
    '.lock-waf*',

xc16 compiler

    'build/xc16',

Flask webapp files.

    'build/Flask/config.py',
    'build/Flask/tmp.html',
    'build/Flask/alembic/versions',

Heroku files

    '.heroku',
    '.profile.d',

Include files

    '**/*.inc',

Files written without CodeChat.

    '2015-fall/26-Aug.s',
    '2015-fall/28-Aug.s',
    '2015-fall/31-Aug.s',
    '2015-fall/2-Sep.s',
    '2015-fall/4-Sep.s',
    '2015-fall/9-Sep.s',
    '2015-fall/11-Sep.s',
    '2015-fall/9-Oct.c',
    '2015-fall/12-Oct.c',
    '2015-fall/14-Oct.c',
    '2015-fall/16-Oct.c',
    '2015-fall/19-Oct.c',

FreeRTOS

    'book/rtos_state_machines/FreeRTOSv9.0.0',
]
 

keep_warnings: If true, keep warnings as “system message” paragraphs in the built documents. Regardless of this setting, warnings are always written to the standard error stream when sphinx-build is run. CodeChat note: This should always be True; doing so places warnings next to the offending text in the web view, making them easy to find and fix.

keep_warnings = True
 

numfig: If true, figures, tables and code-blocks are automatically numbered if they have a caption. See also numref.

numfig = True

Extensions

CodeChat

CodeChat note: A dict of {glob, lexer_alias}, which uses lexer_alias (e.g. a lexer’s short name) to analyze any file wihch matches the given glob.

CodeChat_lexer_for_glob = {
    '*.s': 'NASM',

Otherwise, Pygments picks the wrong lexer for CSS...

    '*.css': 'CSS',

... and for JavaScript.

    '*.js': 'JavaScript',

Pretend some files are Python, to at least parse comments.

    'build/Heroku/requirements.txt': 'python',
    'build/Heroku/Procfile': 'python',
    '*.gitignore': 'python',
}

CodeChat note:: This is a list of exclude_patterns which applies only to source documents; exclude_patterns will exclude the given files from all of Sphinx (for example, files here won’t be included even if they’re mentioned in html_static_path.

CodeChat_excludes = [
    'build/Sphinx/static/annotator.min.js',
]

Inline syntax highlight

inline_highlight_respect_highlight: Use the language specified by the highlight directive to syntax highlight code role contents.

inline_highlight_respect_highlight = True
inline_highlight_literals = False

SphinxBookExtension

For authoring, show the answers to make sure the formatting works. When publishing, hide them.

SphinxBookExtension_showAnswers = False

Options for HTML output

html_theme: The theme to use for HTML and HTML Help pages. See the Alabaster installation docs.

html_theme = 'alabaster'
 

html_theme_options: Theme options are theme-specific and customize the look and feel of a theme further.

See http://alabaster.readthedocs.io/en/latest/customization.html#theme-options.

html_theme_options = {
    'show_related': True,
}
 

html_style: The style sheet to use for HTML pages.

##html_style = None
 

html_static_path: 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. CodeChat note: This must always include CodeChat.css.

Copy Annotator scripts, copy interactive feedback files, copy jQuery scripts, and copy the CodeChat style sheet.

html_static_path = [
    'build/Sphinx/static',
    'build/Flask/templates/flask-user.css',
]
 

html_extra_path: A list of paths that contain extra files not directly related to the documentation, such as robots.txt or .htaccess.

html_extra_path = []
 

html_context: A dictionary of values to pass into the template engine’s context for all pages.

html_context = {
    'css_files': [

Include the feedback CSS.

        '_static/feedback.css',

Not sure why I need this – CodeToRestSphinx adds it programmatically.

        '_static/CodeChat.css',
    ],
}

def setup(app):

This code adds script files to each HTML file produced. Defining html_context.script_files works...but overrides all other values there (such as those populated by Sphinx in Sphinx.builders.html.StandaloneHTMLBuilder.script_files (see Sphinx.builders.html.StandaloneHTMLBuilder.prepare_writing, line 383 in v1.4.8) or MathJax additions via app.add_javascript. Instead, use add_javascript to merge these into existing script files. Note that add_javascript assumes a prefix of _static.

This relies on entries in html_static_path to copy the needed files to the _static directory.

Include the Annotator script.

    app.add_javascript('annotator.min.js')

Include the feedback script.

    app.add_javascript('feedback1.js')
 

html_last_updated_fmt: If not ‘’, a ‘Last updated on:’ timestamp is inserted at every page bottom, using the given strftime format.

html_last_updated_fmt = '%b, %d, %Y'
 

html_use_smartypants: If true, SmartyPants will be used to convert quotes and dashes to typographically correct entities.

html_use_smartypants = True
 

html_sidebars: Custom sidebar templates, maps document names to template names. Set this per the Alabaster installation docs.

html_sidebars = {
    '**': [
        'about.html',
        'navigation.html',
        'relations.html',
        'searchbox.html',
    ],
}
 

html_show_sourcelink: If true, links to the reST sources are added to the pages.

html_show_sourcelink = False
 

html_copy_source: If true, the reST sources are included in the HTML build as _sources/name. Warning: If this config value is set to False, the JavaScript search function will only display the titles of matching documents, and no excerpt from the matching contents.

Since the source contains answers, don’t copy it.

html_copy_source = False