DOCSEARCHbyAlgolia
Submit Docs

nbsphinx Documentation

repository·master·Indexed 19 days ago

https://github.com/spatialaudio/nbsphinx

Jupyter Notebook Tools for Sphinx that provide integration of notebooks into Sphinx documentation. Features include support for Markdown files via Jupytext, BibTeX references, thumbnail link galleries, and the ability to embed Sphinx-generated content into LaTeX documents. It also includes specialized reST directives like .. nbinfo:: and .. nbwarning::, and a raises-exception cell tag to prevent specific notebook errors from halting the build process.

Tokens
17.8K
Snippets
86
Records
110
Agent score
64%

What's inside nbsphinx

  1. Understand the content sources in nbsphinx documentation

    master

    The nbsphinx documentation is composed of multiple source formats. Most content is generated directly from Jupyter notebooks, but some sections use standard Sphinx reStructuredText or alternative storage formats for notebooks.

    Key distinctions:

    • Jupyter Notebooks: The primary source for most documentation pages.
    • reStructuredText: Used for standard documentation sections like contributing, references, and version-history.
    • Custom Formats: Some sections (e.g., custom-formats, gallery/due_rst, a-markdown-file) use alternative storage formats for Jupyter notebooks instead of the standard .ipynb format.

  4. Configure BibTeX references in Sphinx

    master

    To use BibTeX citations in your notebooks and source files, install the sphinxcontrib.bibtex extension and configure it in your conf.py.

    Configuration Steps

    1. Add sphinxcontrib.bibtex to your extensions list.
    2. Define bibtex_bibfiles with a list of your .bib files.
    3. Set bibtex_reference_style (e.g., 'author_year').

    Citation Types

    • Standard Citation: :cite:key``
    • In-text Citation: :cite:t:key``
    • Footnote Citation (requires sphinxcontrib.bibtex >= 2.0.0): :footcite:key``
    • In-text Footnote Citation: :footcite:t:key``

    To render the bibliography list in a reST file, use the .. bibliography:: or .. footbibliography:: directive.

    # conf.py
extensions = [
    'nbsphinx',
    'sphinxcontrib.bibtex',
]

bibtex_bibfiles = ['my-references.bib']
bibtex_reference_style = 'author_year'
    .. bibliography::

.. footbibliography::

  6. Use Markdown files via Jupytext in nbsphinx

    master

    By default, Sphinx does not handle Markdown files. To use Markdown files as Sphinx source files within nbsphinx, you can use jupytext to treat them as custom notebook formats.

    1. Install the jupytext package.
    2. Configure nbsphinx_custom_formats in your Sphinx conf.py to map the .md extension to a Jupytext reader and specify your preferred Markdown flavor (e.g., Rmd).
    nbsphinx_custom_formats = {
    '.md': ['jupytext.reads', {'fmt': 'Rmd'}],
}

  7. Use Math in Markdown files

    master

    Mathematical equations can be included in Markdown files using LaTeX syntax. You can use inline math or separate equation blocks.

    Inline math: Use $ ... $. Block math: Use \begin{equation*} ... \end{equation*}.

    $	ext{e}^{i\pi} = -1$

\begin{equation*}
\int\limits_{-\	ext{infinity}}^{\\infty} f(x) \\delta(x - x_0) dx = f(x_0)
\end{equation*}

  8. Install nbsphinx for development

    master

    To contribute to nbsphinx, install the development version (master branch) in editable mode using pip. This allows you to make changes to the source code and see them reflected immediately without re-installing.

    Before installing, ensure you have met the necessary prerequisites.

    git clone https://github.com/spatialaudio/nbsphinx.git
cd nbsphinx
python3 -m pip install -e .

  9. Compile the final LaTeX document using latexmk

    master

    Because the .tex files generated in the Sphinx _build directory are based on a minimalistic template and are not standalone documents, you cannot run LaTeX directly inside the _build directory.

    Instead, you must run the compilation from the directory containing your main hand-written LaTeX file (e.g., my-latex-document.tex) using latexmk.

    latexmk -pv

  10. Build Sphinx LaTeX files for inclusion in a larger document

    master

    To prepare Sphinx content for inclusion in a larger LaTeX document, run Sphinx from the directory containing your local conf.py (which overrides original settings), pointing to the original source directory.

    Use the -c . flag to specify the current directory as the configuration directory and -b latex to specify the LaTeX builder.

    python -m sphinx ../doc _build -c . -b latex

  11. Link to Notebooks and Sphinx source files in reStructuredText

    master

    You can link to Jupyter Notebooks or other Sphinx source files within a standard .rst file using relative paths. This method is compatible with GitHub and other docutils renderers.

    Link Variants

    • Standard Hyperlink: Use a relative path with a label.
    • Link with spaces: Surround the link text with backticks.
    • Anonymous Hyperlink: Use __ followed by the path.
    • Embedded URIs: Use the link <path> syntax.
    • Subsection Links: Append # followed by the section title (replace spaces with hyphens) to the path.

    Note: These links work in standard reStructuredText environments and are not limited to Sphinx-specific features.

    .. _link: subdir/a-notebook-in-a-subdir.ipynb

using a relative path to the local file: link_.

.. _"a notebook link": subdir/a-notebook-in-a-subdir.ipynb

surround it with backticks: `a notebook link`_.

__ subdir/a-notebook-in-a-subdir.ipynb

like this `link <subdir/a-notebook-in-a-subdir.ipynb>`__.

.. _subsection: subdir/a-notebook-in-a-subdir.ipynb#A-Sub-Section

For example, see this subsection_.

  12. Build Sphinx documentation (HTML and LaTeX)

    master

    To verify changes to the documentation, build the HTML or LaTeX output locally using setup.py.

    1. Install documentation dependencies: python3 -m pip install -r doc/requirements.txt

    2. Build HTML documentation: python3 setup.py build_sphinx (Output: build/sphinx/html/)

    3. Build LaTeX documentation: python3 setup.py build_sphinx -b latex (Output: build/sphinx/latex/)

    # Install requirements
python3 -m pip install -r doc/requirements.txt

# Build HTML
python3 setup.py build_sphinx

# Build LaTeX
python3 setup.py build_sphinx -b latex