You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
77 lines
2.1 KiB
77 lines
2.1 KiB
"""Crude Sphinx extension for examples documentation.
|
|
|
|
© 2019 Paul Natsuo Kishimoto <mail@paul.kishimoto.name>
|
|
Licensed under the GNU GPLv3: https://www.gnu.org/licenses/gpl-3.0.html
|
|
Star: https://gist.github.com/khaeru/3185679f4dd83b16a0648f6036fb000e
|
|
|
|
Enable by adding to conf.py::
|
|
|
|
sys.path.append('path/to/this/file')
|
|
extensions.append('examples')
|
|
|
|
# Root path for examples documentation, relative to conf.py.
|
|
# If your source code is laid out like:
|
|
#
|
|
# - BASE/
|
|
# - doc/
|
|
# - source/
|
|
# - conf.py
|
|
# - my_module/
|
|
# - __init__.py
|
|
# - doc.rst
|
|
#
|
|
# …then examples_source should be like:
|
|
|
|
examples_source = '../../my_module'
|
|
|
|
# Destination path for copied files, relative to conf.py.
|
|
# For instance, the following:
|
|
|
|
examples_dest = 'generated'
|
|
|
|
# …results in files being copied to 'BASE/doc/source/generated'
|
|
|
|
find_examples_docs() performs two replacements:
|
|
|
|
1. A file like my_module/submodule/doc.rst is copied to
|
|
my_module/submodule.rst.
|
|
2. A file like my_module/submodule/doc/index.rst is copied to
|
|
my_module/submodule.rst
|
|
|
|
All other paths are not modified.
|
|
|
|
'Crude' means:
|
|
- Old files in the examples_dest directory are not removed automatically.
|
|
- It's not tested; bad config values will cause strange behaviour.
|
|
|
|
"""
|
|
|
|
import glob
|
|
import os
|
|
from os import PathLike
|
|
from pathlib import Path
|
|
from shutil import copy2, copytree, rmtree
|
|
|
|
from sphinx.util import status_iterator
|
|
|
|
def find_examples_docs(src_dir, target_dir):
|
|
"""Yield tuples of (source, dest) filenames.
|
|
|
|
The first element in each tuple is the path to a file in *src_dir* that
|
|
matches '**/{match}'. The second is the same path, below *target_dir*,
|
|
modified as described above.
|
|
"""
|
|
for source in glob.glob(os.path.join(src_dir,'**'), recursive=True):
|
|
print(source)
|
|
if not os.path.isdir(source):
|
|
dest = source
|
|
print(dest)
|
|
yield source, target_dir / dest
|
|
|
|
|
|
def config_inited(app, config):
|
|
os.system('make examples')
|
|
|
|
def setup(app):
|
|
app.connect('config-inited', config_inited)
|