###############
Notes on Sphinx
###############

Theming
#######

This collection of pages uses a modified version of the Sphinx haiku theme.
Thankfully, it was relatively easy to modify and does not involve copying
the whole theme.

* The config file:

  .. literalinclude:: ../_sphinx/_themes/nwf-haiku/theme.conf
     :language: ini

* The CSS overrides:

  .. literalinclude:: ../_sphinx/_themes/nwf-haiku/static/haikuish.css  
     :language: css

* The HTML overrides:

  .. literalinclude:: ../_sphinx/_themes/nwf-haiku/layout.html
     :language: html

Extensions
##########

Disabling Searching for Particular Directories
----------------------------------------------

Sometimes we don't want to leak data via search pages.  This is a very
hackish extension that directly modifies the HTML builder object, since
there does not appear to be a better way.

.. literalinclude:: ../_sphinx/nwfext_disable_search.py
   :language: python

Separately, the ``secret/`` path and ``_source/secret/`` paths are protected
by the web server itself so that unauthenticated clients may not read them;
otherwise, there'd be little point!

Removing Document Title From Markup
-----------------------------------

The theme I am using places the title up top specially, but it *also*
remains in the document tree and so gets rendered first thing.  That looks
bad.  This extension surgically removes the document title from pages
without altering the sphinx metadata and then promotes the title's sibling
nodes to take the place of the former page container.

.. literalinclude:: ../_sphinx/nwfext_doctitle.py
   :language: python

Hacking Generality Into Toctrees
--------------------------------

Despite it being a long-standing feature request
(https://github.com/sphinx-doc/sphinx/issues/701) with a few PRs taking
a stab at it (some from yours truly), sphinx core is hesitant to extend
the semantics of toctrees or muck about in their core.  So, instead, I
present the following **truly terrible** workaround.

This is an extension which adds a ``toctreeish`` directive that *manually
parses* the toctree entries and *fakes* the references that sphinx would
otherwise generate.  (It then causes Sphinx to perceive a *hidden* toctree so
that the rest of the deep, internal document cluster and toctree resolution
magic happens.)  The key feature is that entries that begin with an underscore
followed by space will have the rest of their literal text parsed by
``docutils`` and then inserted into the list.  It is in use on this site in
:doc:`/publications-and-talks/index`, which contains (roughly) ::

    .. toctreeish::

       foo
       bar
       _ :ref:`baz title <baz#ref>`

It's gross, it's terrible, but it means I don't have to carry around a patched
Sphinx or link to the wrong place in my list of publications.  Hooray?

.. literalinclude:: ../_sphinx/nwfext_toctreeish.py
   :language: python

Bibliographic Management
########################

The entire :doc:`../publications-and-talks/index` section of this site is
generated from a bib file, a series of small ReStructredText inputs, and the
downloads themselves.  The bulk of the work is done by :download:`this TCL
script <../publications-and-talks.in/gen/gen.tcl>`.  The two parameter files
for ``bibtool`` are:

* :download:`gen-bibtool-incl.rst <../publications-and-talks.in/gen/gen-bibtool-incl.rsc>`
* :download:`gen-bibtool-iter.rst <../publications-and-talks.in/gen/gen-bibtool-iter.rsc>`