diff options
author | Loïc Vital <mugulmotion@gmail.com> | 2022-10-12 19:25:10 +0300 |
---|---|---|
committer | Loïc Vital <mugulmotion@gmail.com> | 2022-10-12 19:25:10 +0300 |
commit | cec2c79d6a31d532d5f9dfc62830b4cfc89b8278 (patch) | |
tree | 809bac356e0b8393469c1755da9acb5a5f079809 | |
parent | e022b377c42d50839b66cb1e38fbe86f58e65b5a (diff) |
[docs] generate extra node doc with custom extension
-rw-r--r-- | docs/source/_ext/fetch_md.py | 8 | ||||
-rw-r--r-- | docs/source/_ext/meshroom_doc.py | 60 | ||||
-rw-r--r-- | docs/source/_templates/autosummary/class.rst | 35 | ||||
-rw-r--r-- | docs/source/changes.rst | 3 | ||||
-rw-r--r-- | docs/source/conf.py | 3 | ||||
-rw-r--r-- | docs/source/index.rst | 3 | ||||
-rw-r--r-- | docs/source/install.rst | 3 |
7 files changed, 102 insertions, 13 deletions
diff --git a/docs/source/_ext/fetch_md.py b/docs/source/_ext/fetch_md.py index 20f0462a..bfc3da09 100644 --- a/docs/source/_ext/fetch_md.py +++ b/docs/source/_ext/fetch_md.py @@ -38,14 +38,10 @@ class Relinker(SparseNodeVisitor): class FetchMd(Directive): - required_arguments = 2 - - def arg_path(self): - if self.arguments[0] == ':file:': - return self.arguments[1] + required_arguments = 1 def run(self): - path = os.path.abspath(os.getenv('PROJECT_DIR') + '/' + self.arg_path()) + path = os.path.abspath(os.getenv('PROJECT_DIR')+'/'+self.arguments[0]) result = [] try: with open(path) as file: diff --git a/docs/source/_ext/meshroom_doc.py b/docs/source/_ext/meshroom_doc.py new file mode 100644 index 00000000..acde4aab --- /dev/null +++ b/docs/source/_ext/meshroom_doc.py @@ -0,0 +1,60 @@ +from docutils import nodes +from docutils.parsers.rst import Directive +from myst_parser.docutils_ import Parser +from myst_parser.mdit_to_docutils.base import make_document + +import importlib +from meshroom.core import desc + + +class MeshroomDoc(Directive): + + required_arguments = 4 + + def parse_args(self): + module_name = self.arguments[self.arguments.index(':module:')+1] + class_name = self.arguments[self.arguments.index(':class:')+1] + return (module_name, class_name) + + def run(self): + result = [] + # Import module and class + module_name, class_name = self.parse_args() + module = importlib.import_module(module_name) + node_class = getattr(module, class_name) + # Class inherits desc.Node + if issubclass(node_class, desc.Node): + node = node_class() + parser = Parser() + # Category + doc = make_document(parser_cls=Parser) + parser.parse('**Category**: {}'.format(node.category), doc) + result.extend(doc.children) + # Documentation + doc = make_document(parser_cls=Parser) + parser.parse(node.documentation, doc) + result.extend(doc.children) + # Inputs + text_inputs = '**Inputs**: \n' + for attr in node.inputs: + text_inputs += '- {} ({})\n'.format(attr._name, attr.__class__.__name__) + doc = make_document(parser_cls=Parser) + parser.parse(text_inputs, doc) + result.extend(doc.children) + # Outputs + text_outputs = '**Outputs**: \n' + for attr in node.outputs: + text_outputs += '- {} ({})\n'.format(attr._name, attr.__class__.__name__) + doc = make_document(parser_cls=Parser) + parser.parse(text_outputs, doc) + result.extend(doc.children) + return result + + +def setup(app): + app.add_directive("meshroom_doc", MeshroomDoc) + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst new file mode 100644 index 00000000..03dc3878 --- /dev/null +++ b/docs/source/_templates/autosummary/class.rst @@ -0,0 +1,35 @@ +{{ fullname | escape | underline}} + + +.. meshroom_doc:: + :module: {{ module }} + :class: {{ objname }} + + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {% block methods %} + .. automethod:: __init__ + + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + {% for item in methods %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/source/changes.rst b/docs/source/changes.rst index 1b84907c..6f46995b 100644 --- a/docs/source/changes.rst +++ b/docs/source/changes.rst @@ -2,5 +2,4 @@ Release Notes ============= -.. fetch_md:: - :file: CHANGES.md +.. fetch_md:: CHANGES.md diff --git a/docs/source/conf.py b/docs/source/conf.py index 709e205a..6f58c912 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -25,7 +25,8 @@ author = 'AliceVision Association' extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', - 'fetch_md' + 'fetch_md', + 'meshroom_doc' ] templates_path = ['_templates'] diff --git a/docs/source/index.rst b/docs/source/index.rst index bd01d0c5..e1c45124 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,5 +11,4 @@ Welcome to meshroom's documentation! changes -.. fetch_md:: - :file: README.md +.. fetch_md:: README.md diff --git a/docs/source/install.rst b/docs/source/install.rst index b05e1676..a6500ed1 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -2,5 +2,4 @@ Install ======= -.. fetch_md:: - :file: INSTALL.md +.. fetch_md:: INSTALL.md |