Commit c4a6abad authored by Paul McCarthy's avatar Paul McCarthy 🚵
Browse files

DOC: use substitutions instead of modifying source files

parent 30359ec2
......@@ -62,4 +62,12 @@ rules that it applies.
Command-line reference
----------------------
All of the command-line options that FUNPACK accespts are documented below::
All of the command-line options that FUNPACK accespts are documented below:
..
Defined in conf.py
.. codesub:: none
|funpack_cli_help|
......@@ -17,19 +17,32 @@
# -- Project information -----------------------------------------------------
import os.path as op
import datetime
import funpack
import funpack.config as config
import funpack.custom as custom
date = datetime.date.today()
date = datetime.date.today()
author = 'Paul McCarthy'
project = 'FUNPACK'
release = '{}'.format(funpack.__version__)
copyright = f'{date.year}, Paul McCarthy, University of Oxford, Oxford, UK'
project = 'FUNPACK'
copyright = u'{}, Paul McCarthy, University of Oxford, Oxford, UK'.format(
date.year)
author = 'Paul McCarthy'
# substitutions used in various places throughout the docs
custom.registerBuiltIns()
docdir = op.dirname(op.abspath(__file__))
cfgdir = op.relpath(funpack.findConfigDir(), docdir)
release = '{}'.format(funpack.__version__)
# See funpack_sphinx_exts.SubstitutionCode -
# hack to allow multi-line substitutions
clihelp = config.makeParser().format_help().replace('\n', '//n//')
rst_prolog = f"""
.. |cfgdir| replace:: {cfgdir}
.. |funpack_cli_help| replace:: {clihelp}
"""
# -- General configuration ---------------------------------------------------
......@@ -42,7 +55,7 @@ extensions = [
'sphinx.ext.viewcode',
'sphinx.ext.autosummary',
'nbsphinx',
'sphinx_details',
'funpack_sphinx_exts',
]
# Add any paths that contain templates here, relative to this directory.
......
......@@ -30,26 +30,28 @@ The ``fmrib`` configuration profile is split across several files, each of
which are described below. Click on the arrow to the left of each section to
view the contents of that file.
..
|cfgdir| is defined in conf.py
.. details::
.. summary:: ``funpack/configs/fmrib.cfg``: Top-level configuration file,
containing general settings, and references to the other
configuration files.
.. include:: ../funpack/configs/fmrib.cfg
.. includesub:: |cfgdir|/fmrib.cfg
:literal:
.. details::
.. summary:: ``funpack/configs/local.cfg``: Included by ``fmrib.cfg``.
Contains some miscellaneous settings related to performance
and error-checking.
.. include:: ../funpack/configs/local.cfg
.. includesub:: |cfgdir|/local.cfg
:literal:
.. details::
.. summary:: ``funpack/configs/fmrib/categories.tsv``: Definition of FMRIB
datafield categories - groups of related data-fields.
Categories can be selected with the ``-c/--category`` option.
.. include:: ../funpack/configs/fmrib/categories.tsv
.. includesub:: |cfgdir|/fmrib/categories.tsv
:literal:
.. details::
......@@ -59,7 +61,7 @@ view the contents of that file.
list of values which will be removed. Each rule is applied to
every data-field that uses the corresponding data-coding. Only
the first 20 rules are shown here.
.. include:: ../funpack/configs/fmrib/datacodings_navalues.tsv
.. includesub:: |cfgdir|/fmrib/datacodings_navalues.tsv
:literal:
:end-line: 21
......@@ -72,7 +74,7 @@ view the contents of that file.
with. Each rule is applied to every data-field that uses the
corresponding data-coding. Only the first 20 rules are shown
here.
.. include:: ../funpack/configs/fmrib/datacodings_recoding.tsv
.. includesub:: |cfgdir|/fmrib/datacodings_recoding.tsv
:literal:
:end-line: 21
......@@ -83,7 +85,7 @@ view the contents of that file.
(see :ref:`here <cleaning_functions>` for an overview of all
built-in cleaning functions). Only the first 20 rules are
shown here.
.. include:: ../funpack/configs/fmrib/variables_clean.tsv
.. includesub:: |cfgdir|/fmrib/variables_clean.tsv
:literal:
:end-line: 21
......@@ -92,7 +94,7 @@ view the contents of that file.
format for all date/time data-fields. These functions are
defined in the built-in :mod:`funpack.plugins.fmrib` plugin
module.
.. include:: ../funpack/configs/fmrib/datetime_formatting.tsv
.. includesub:: |cfgdir|/fmrib/datetime_formatting.tsv
:literal:
.. details::
......@@ -103,7 +105,7 @@ view the contents of that file.
data-fields, and the ``ChildValues`` column is a value to set
the data-field to when the expression evaluates to true. Only
the first 20 rules are shown here.
.. include:: ../funpack/configs/fmrib/variables_parentvalues.tsv
.. includesub:: |cfgdir|/fmrib/variables_parentvalues.tsv
:literal:
:end-line: 21
......@@ -112,7 +114,7 @@ view the contents of that file.
applied to the data set after all cleaning stages have been
performed. See :ref:`here <processing_functions>` for an
overview of all of the built-in processing functions.
.. include:: ../funpack/configs/fmrib/processing.tsv
.. includesub:: |cfgdir|/fmrib/processing.tsv
:literal:
|
......@@ -128,15 +130,15 @@ logging information and additional summary files.
.. details::
.. summary:: ``fmrib_standard.cfg``
.. include:: ../funpack/configs/fmrib_standard.cfg
.. includesub:: |cfgdir|/fmrib_standard.cfg
:literal:
.. details::
.. summary:: ``fmrib_logs.cfg``
.. include:: ../funpack/configs/fmrib_logs.cfg
.. includesub:: |cfgdir|/fmrib_logs.cfg
:literal:
.. details::
.. summary:: ``fmrib_cats.cfg``
.. include:: ../funpack/configs/fmrib_cats.cfg
.. includesub:: |cfgdir|/fmrib_cats.cfg
:literal:
|
......@@ -149,5 +151,5 @@ newly added data fields that you have not yet encountered.
.. details::
.. summary:: ``fmrib_new_release.cfg``
.. include:: ../funpack/configs/fmrib_new_release.cfg
.. includesub:: |cfgdir|/fmrib_new_release.cfg
:literal:
#!/usr/bin/env fslpython
# sphinx extension which embeds content wihtin a HTML <details> element
#
# sphinx extensions which:
# - embed content wihtin a HTML <details> element
# - allows subsitutions in paths passed to include::
# - allows subsitutions in codeblock::
from docutils import nodes
from docutils.parsers.rst import directives
from docutils.parsers.rst import Directive
from sphinx.util.nodes import nested_parse_with_titles, nested_parse_with_titles
from docutils import nodes
from docutils.parsers.rst import Directive
from sphinx.directives.other import Include
from sphinx.directives.code import CodeBlock
from sphinx.util.nodes import nested_parse_with_titles
class DetailsNode(nodes.Element):
......@@ -40,9 +45,31 @@ def visitDetailsNode(self, node):
def departDetailsNode(self, node):
self.body.append("</p></details>")
class SubstitutionInclude(Include):
def run(self):
filename = self.arguments[0]
for orig, repl in self.state.document.substitution_defs.items():
filename = filename.replace(f'|{orig}|', repl.astext())
self.arguments[0] = filename
return super().run()
class SubstitutionCode(CodeBlock):
def run(self):
newcontent = []
for line in self.content:
for orig, repl in self.state.document.substitution_defs.items():
line = line.replace(f'|{orig}|', repl.astext())
# hack to allow multi-line substitutions
line = line.replace('//n//', '\n')
newcontent.append(line)
self.content = newcontent
return super().run()
def setup(app):
app.add_node(DetailsNode, html=(visitDetailsNode, departDetailsNode))
app.add_node(SummaryNode, html=(visitSummaryNode, departSummaryNode))
app.add_directive('details', DetailsDirective)
app.add_directive('summary', SummaryDirective)
app.add_directive('details', DetailsDirective)
app.add_directive('summary', SummaryDirective)
app.add_directive('includesub', SubstitutionInclude)
app.add_directive('codesub', SubstitutionCode)
#!/usr/bin/env python
import shutil
import sys
import os.path as op
from setuptools import setup, find_packages, Command
......@@ -58,23 +59,18 @@ class doc(Command):
docdir = op.join(op.dirname(__file__), 'doc')
destdir = op.join(docdir, 'html')
# so sphinx can find our custom extensions
sys.path.append(docdir)
if op.exists(destdir):
shutil.rmtree(destdir)
import funpack.scripts.generate_notebooks as gennb
import funpack.config as config
import funpack.custom as custom
import funpack.util as util
import sphinx.cmd.build as sphinx_build
# generate doc/command_line.rst
custom.registerBuiltIns()
clifile = op.join(basedir, 'doc', 'command_line.rst')
clihelp = config.makeParser().format_help().split('\n')
clihelp = [f' {line}' for line in clihelp]
clihelp = '\n'.join(clihelp)
with open(clifile, 'at') as f:
f.write(f'\n{clihelp}')
# generate doc/demo.ipynb
demofile = op.join(basedir, 'doc', 'demo.ipynb')
if not op.exists(demofile):
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment