#####################################################################
Configuration
#####################################################################

.. _Brad Stancel: https://bradstancel.com/
.. |date| date:: %m/%d/%Y

:Authors: `Brad Stancel`_
:Created:  04/01/2020
:Modified: |date|

.. _doc-system-configuration-overview:

*********************************************************************
Configuration Overview
*********************************************************************

Check out the configuration in the :ref:`Sphinx snippets section here <cheat-sheet-sphinx-snippets>`


**Remove Blank Pages from Sphinx PDF**

.. code-block:: python

    latex_elements = {
        'extraclassoptions': 'openany,oneside'
    }



*********************************************************************
Extensions
*********************************************************************

`Here is a link showing the built-in extension for Sphinx <https://www.sphinx-doc.org/en/master/usage/extensions/index.html>`_.


Here are some key Sphinx extensions:

- `sphinxcontrib-mermaid <https://github.com/mgaitan/sphinxcontrib-mermaid>`_
- `sphinx-copybutton <https://sphinx-copybutton.readthedocs.io/en/latest/>`_
- `sphinx.ext.intersphinx <https://docs.readthedocs.com/platform/latest/guides/intersphinx.html>`_



*********************************************************************
Example Configuration
*********************************************************************

Here is a real ``conf.py`` file from one of my documentation repos. This is a good starting point to copy and paste from and then just change / add / remove any needed items or text.


.. code-block:: python

    # Configuration file for the Sphinx documentation builder.
    #
    # For the full list of built-in configuration values, see the documentation:
    # https://www.sphinx-doc.org/en/master/usage/configuration.html

    # -- Project information -----------------------------------------------------
    # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

    project = 'AI Documentation'
    copyright = '2025, Brad Stancel'
    author = 'Brad Stancel'
    release = '1.0.0'

    html_favicon = '_static/_images/favicon.ico'
    html_show_sourcelink = False

    # -- General configuration ---------------------------------------------------
    # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

    extensions = [
        'sphinx_rtd_theme',
        'sphinxcontrib.youtube',
        'recommonmark',
        'sphinx.ext.extlinks',
        'sphinx.ext.graphviz',
        'sphinx.ext.intersphinx',
        'sphinxcontrib.plantuml',
        'sphinxcontrib.mermaid',
        'sphinx_copybutton'
    ]

    intersphinx_mapping = {
        'linux': ('https://writings.bradstancel.com/linux-docs', None),
        'server-programs': ('https://writings.bradstancel.com/server-programs', None)
    }
    # We recommend adding the following config value.
    # Sphinx defaults to automatically resolve *unresolved* labels using all your Intersphinx mappings.
    # This behavior has unintended side-effects, namely that documentations local references can
    # suddenly resolve to an external location.
    # See also:
    # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
    intersphinx_disabled_reftypes = ["*"]

    # Add any paths that contain templates here, relative to this directory.
    templates_path = ['_templates']

    # 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 = []


    # -- Options for HTML output -------------------------------------------------

    # The theme to use for HTML and HTML Help pages.  See the documentation for
    # a list of builtin themes.
    #
    html_theme = 'sphinx_rtd_theme'

    # 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']

    #Brad Edit - Adding a custom CSS file to see if I can get colored text in CSV Tables
    html_css_files = [
    '_css/sphinx-custom.css'
    ]


    # Brad Edit - Put any links here that you want to be able to reference throughout the site
    # extlinks = {
    # }

    # Brad Edit - Remove blank pages when creating PDF's with 'make latexpdf' - huge timesaver
    latex_elements = {
    'extraclassoptions': 'openany,oneside'
    }


|
|

*********************************************************************
Links and References
*********************************************************************

Any links or references used in creating this documentation should be listed below.

- https://www.sphinx-doc.org/en/1.8/usage/configuration.html

- The below `html_extra_path` setting allows for deploying files like robots.txt during builds.
    - https://www.sphinx-doc.org/en/1.8/usage/configuration.html#confval-html_extra_path


- `Sphinx docs: Remove blank pages from generated PDFs? <https://stackoverflow.com/questions/5422997/sphinx-docs-remove-blank-pages-from-generated-pdfs>`_

- `How to create a PDF-out-of-Sphinx-documentation-tool <https://stackoverflow.com/questions/39534718/how-to-create-a-pdf-out-of-sphinx-documentation-tool>`_

- `Gist with Linux Commands to Install Latex and Fonts in order to generate Sphinx PDF's <https://gist.github.com/rain1024/98dd5e2c6c8c28f9ea9d>`_

- `VERY USEFUL - Awesome Sphinx (Python Documentation Generator) - Github <https://github.com/yoloseem/awesome-sphinxdoc>`_

- `List of Sphinx Additional Sphinx Extensions <https://sphinx-extensions.readthedocs.io/en/latest/>`_

- `sphinxcontrib-mermaid Sphinx extension <https://github.com/mgaitan/sphinxcontrib-mermaid>`_
- `sphinxcontrib-mermaid PyPi <https://pypi.org/project/sphinxcontrib-mermaid/>`_

- `sphinx-copybutton <https://sphinx-copybutton.readthedocs.io/en/latest/>`_

- `Intersphinx Extension <https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html>`_