##################################
Using Directories for Sphinx Pages
##################################

    Creating `Sphinx`_ pages as ``./foo/index.rst`` has a number of benefits over
    ``./foo.rst`` including path consistency and organizing content.

When `I first started playing with ABlog`_, and thus learning more about Python's
wonderful documentation tool `Sphinx`_, I observed that `Sphinx`_ actually creates a
directory in the built HTML output for each `reStructuredText`_ ``./**.rst`` file in the
source.  For example, if the source for this post had been
``./blog/sphinx-page-dirs.rst``, `Sphinx`_ would render that to
``./_website/blog/sphinx-page-dirs/index.html``.

One consequence of this is that a relative link to another area of the site will be
broken in the rendered HTML build output if it's correct in the ``./**.rst`` source
file.  For example, if ``./about.rst`` contains a link such as:

.. code-block:: rst

   See `the blog area to see all posts <./blog/>`_.

The `Sphinx`_ HTML build output will render that ``./about.rst`` file to
``./about/index.html`` and thus the link will point to ``/about/blog/`` instead of the
intended ``/blog/``.  I dimly recall encountering such path issues with other types of
reST path references as well.  Path consistency is also particularly handy for editors
or other tools that can infer enough to open files from path references in other files,
such as `FFAP`_ in `Emacs`_.  Writing the source reST for a page as
``./about/index.rst`` in the first place nicely avoids those problems and empowers such
tools.

I'm not a big fan of embedding code of one sort into content (or code) of another sort.
For example, as big an `Org-mode`_ fan as I am, I've never been able to get into using
`Babel`_.  In this case, when writing documentation or other text content, I resist
embedding code into source text files and prefer to have such code in separate files
next to the text.  If the code I want to include in documentation is actual used code,
as was the case with `the export/import scripts that migrated this blog`_, then it saves
time copying and pasting and prevents out-of-date content when forgetting to do so.
Even if it is example or demonstration code of more than a few lines, having it in
separate sibling files supports using all our favorite tools (static analysis, IDEs,
editors, etc.) which further prevents incorrect or misleading examples.  So instead of
`reStructuredText's :: literal blocks`_ or Markdown's indented code blocks I'd much
rather include code from separate files.  Using a directory for such pages,
e.g. ``./blog/migrating-from-plone-to-ablog/``, also allows us to keep such related
files organized neatly together.

Finally, using a directory for a `Sphinx`_ page supports putting all related content
into a separate VCS repository checkout, such as via ``$ git submodule ...``.  This can
be very useful for sharing code related to one page without having to share the source
and VCS history for the whole site.  For example, I have an upcoming post with a
non-trivial amount of working and tested demo code I want to share.  I can use this
approach to make that code and VCS history public while still preserving the option of
having private content or VCS history for the rest of this site.

.. _`reStructuredText`: https://docutils.sourceforge.io/rst.html
.. _`reStructuredText's :: literal blocks`: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#literal-blocks
.. _`Sphinx`: https://www.sphinx-doc.org/en/master/

.. _`Emacs`: https://www.gnu.org/software/emacs/
.. _`Org-mode`: https://orgmode.org/
.. _`Babel`: https://orgmode.org/worg/org-contrib/babel/
.. _`FFAP`: https://www.gnu.org/software/emacs/manual/html_node/emacs/FFAP.html

.. _`I first started playing with ABlog`: ../migrating-from-plone-to-ablog/
.. _`the export/import scripts that migrated this blog`: `I first started playing with ABlog`_

.. meta::
   :description: Creating Sphinx pages as `./foo/index.rst` has a number of
                 benefits over `./foo.rst` including path consistency and organizing
                 content.
   :keywords: Python, reStructuredText, Sphinx, ABlog

.. post:: Apr 5, 2021
   :author: Ross Patterson
   :tags: Python, reStructuredText, Sphinx, ABlog