Python

sphinx extension

  • summary for developing sphinx extension

key sphinx object

  • four key object in sphinx extension

  • package path: sphinx.application.Sphinx

  • usally called app

  • sphinx instance

  • controls most high-level functionality (extension setup, dispatching, production out etc)

  • package path: sphinx.environment.BuildEnvironment

  • build environment object

  • responsible for parsing the source document, stores all metadata

  • access: app.evn

  • package path: sphinx.builders.Builder

  • **convert the parsed documents into an output format`

  • access: app.builder

  • package path: sphinx.config.Config

  • provides the values of configuration values set in conf.py

  • access: app.config or env.config

build process

  • searching for source files in source directory (usally docs folder)

  • extensions are initialized

  • read and parse all the source files

  • ** execute directives and roles **

  • output: doctree for each source file

  • the parsed doctrees are stored on disk

  • some checking

  • transform components

  • **convert doctree to output format (html, latex etc)

  • docutils writer converts nodes of each doctree to output format

developing extension example

0. preparation

  1. create extension folder

  2. update conf.py

Hide code cell content 
%cd ~/sphinx_ext

[Errno 2] No such file or directory: '/home/runner/sphinx_ext'
/home/runner/work/tdc/tdc/docs/dc

!tree . -L 3

.
├──  _md
│   ├── _Untitled.md
│   ├── _jupytext_01.md
│   ├── _myst.md
│   ├── _sphinx_01.md
│   └── _sphinx_02.md
├── autodoc.md
├── jb
│   ├──  _md
│   │   └── _quickstart.md
│   ├── config.md
│   ├── ghp.md
│   ├── img
│   │   ├── ghp_01.png
│   │   ├── ghp_02.png
│   │   ├── ghp_site_01.png
│   │   ├── git_action_02.png
│   │   ├── jb_01.png
│   │   ├── jb_02.png
│   │   └── jb_build_01.png
│   ├── intro_area.md
│   ├── overview.md
│   ├── quick-start.md
│   ├── quickstart.ipynb
│   └── toc.md
├── jupyter-book.md
├── jupytext_01.ipynb
├── markdown.md
├── markup.md
├── mermaid.md
├── myst.ipynb
├── rst.md
├── sphinx.md
├── sphinx_01.ipynb
├── sphinx_02.ipynb
├── sphinx_ext.ipynb
└── thebe.md

4 directories, 33 files

conf.py

# ext_basic 모듈 import를 위한 path 추가
import os
import sys
sys.path.insert(0, os.path.abspath('../ext/'))

# ext_basic extension 추가
extensions = [
    'myst_parser',
    'ext_basic'
]

1. overall code - ext_basic.py

Hide code cell source 
import ext.ext_basic
import inspect

print(inspect.getsource(ext.ext_basic))

---------------------------------------------------------------------------
ModuleNotFoundError                       Traceback (most recent call last)
Cell In[3], line 1
----> 1 import ext.ext_basic
      2 import inspect
      4 print(inspect.getsource(ext.ext_basic))

ModuleNotFoundError: No module named 'ext'

2. setup()

Hide code cell source 
import ext.ext_basic
import inspect

print(inspect.getsource(ext.ext_basic.setup))

    def run(self):
            
        return [
            nodes.raw("", f'{self.content}', format='html')
        ]

3. directive

Hide code cell source 
import ext.ext_basic
import inspect

print(inspect.getsource(ext.ext_basic.basic))

class basic(SphinxDirective):

    has_content = True

    def run(self):
            
        return [
            nodes.raw("", f'{self.content}', format='html')
        ]

4. write .md

```{basic}
```

5. build

!pdm run sphinx-build -a -E docs/ docs/_build/html

Running Sphinx v7.0.1
myst v2.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions=set(), disable_syntax=[], all_links_external=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
building [mo]: all of 0 po files
writing output... 
building [html]: all source files
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [100%] index                                                
looking for now-outdated files... none found
pickling environment... done
checking consistency... /home/yblee/sphinx_ext/docs/basic.md: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] index                                                 
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 1 warning.

The HTML pages are in docs/_build/html.

6. result

Hide code cell source 
from IPython.display import display, HTML
chart = HTML('./docs/_build/html/basic.html')
# or chart = charts.plot(...)
display(chart)
basic extension — sphinx-ext documentation

basic extension

code

```{basic}

sphinx extension test
```

result

['sphinx extension test']
©2023, gritism. | Powered by Sphinx 7.0.1 & Alabaster 0.7.13 | Page source
Previous
autodoc
Next
mermaid