diff options
author | Loïc Vital <mugulmotion@gmail.com> | 2022-10-21 14:42:34 +0300 |
---|---|---|
committer | Loïc Vital <mugulmotion@gmail.com> | 2022-10-21 15:10:00 +0300 |
commit | f3bed081bda887d2c9df953fbdbe30d01829940e (patch) | |
tree | 0362bb1cdf9452a575f973bb9a21c3fb899f4e8f | |
parent | e63b06a3b9a72f6f4bfc27a0e992a90f69f23a8c (diff) |
[docs] commenting custom extensions
-rw-r--r-- | .readthedocs.yaml | 7 | ||||
-rw-r--r-- | docs/source/_ext/fetch_md.py | 14 | ||||
-rw-r--r-- | docs/source/_ext/meshroom_doc.py | 13 | ||||
-rw-r--r-- | docs/source/_ext/utils.py | 8 |
4 files changed, 39 insertions, 3 deletions
diff --git a/.readthedocs.yaml b/.readthedocs.yaml index baf40bb0..5aebe693 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -5,11 +5,12 @@ # Required version: 2 -# Build documentation in the docs/ directory with Sphinx +# Build HTML documentation with Sphinx sphinx: - configuration: docs/source/conf.py + builder: html + configuration: docs/source/conf.py -# Optionally declare the Python requirements required to build your docs +# Python requirements python: install: - requirements: requirements.txt diff --git a/docs/source/_ext/fetch_md.py b/docs/source/_ext/fetch_md.py index 18773dd6..fa85fcc3 100644 --- a/docs/source/_ext/fetch_md.py +++ b/docs/source/_ext/fetch_md.py @@ -1,3 +1,17 @@ +# Sphinx extension defining the fetch_md directive +# +# Goal: +# include the content of a given markdown file +# +# Usage: +# .. fetch_md:: path/to/file.md +# the filepath is relative to the project base directory +# +# Note: +# some markdown files contain links to other files that belong to the project +# since those links are relative to the file location, they are no longer valid in the new context +# therefore we try to update these links but it is not always possible + import os from docutils.nodes import SparseNodeVisitor from docutils.parsers.rst import Directive diff --git a/docs/source/_ext/meshroom_doc.py b/docs/source/_ext/meshroom_doc.py index 965824be..d5151ef7 100644 --- a/docs/source/_ext/meshroom_doc.py +++ b/docs/source/_ext/meshroom_doc.py @@ -1,3 +1,16 @@ +# Sphinx extension defining the meshroom_doc directive +# +# Goal: +# create specific documentation content for meshroom objects +# +# Usage: +# .. meshroom_doc:: +# :module: module_name +# :class: class_name +# +# Note: +# for now this tool focuses only on meshroom nodes + from docutils import nodes from docutils.parsers.rst import Directive from utils import md_to_docutils diff --git a/docs/source/_ext/utils.py b/docs/source/_ext/utils.py index 729aa8a5..cbfbb6b9 100644 --- a/docs/source/_ext/utils.py +++ b/docs/source/_ext/utils.py @@ -1,7 +1,12 @@ +# Utility functions for custom Sphinx extensions + from myst_parser.docutils_ import Parser from myst_parser.mdit_to_docutils.base import make_document +# Given a string written in markdown +# parse its content +# and return the corresponding docutils document def md_to_docutils(text): parser = Parser() doc = make_document(parser_cls=Parser) @@ -9,6 +14,9 @@ def md_to_docutils(text): return doc +# Given a docutils node +# find an attribute that corresponds to a link (if it exists) +# and return its key def get_link_key(node): link_keys = ['uri', 'refuri', 'refname'] for key in link_keys: |