diff --git a/.github/workflows/sphinx-make-page.yml b/.github/workflows/sphinx-make-page.yml index 081a36adb53..f495b0dc9f8 100644 --- a/.github/workflows/sphinx-make-page.yml +++ b/.github/workflows/sphinx-make-page.yml @@ -24,6 +24,12 @@ jobs: run: | python -m pip install --upgrade pip pip install --upgrade --requirement requirements.txt + - name: Install generator parameter library + run: | + cd + git clone https://github.com/PickNikRobotics/generate_parameter_library.git + cd generate_parameter_library/generate_parameter_library_py/ + sudo python setup.py install - name: Install doxygen and graphviz run: sudo apt-get install -y doxygen graphviz - name: Build multiversion with API diff --git a/_ext/generate_parameter_library.py b/_ext/generate_parameter_library.py new file mode 100644 index 00000000000..b48aa9ab40a --- /dev/null +++ b/_ext/generate_parameter_library.py @@ -0,0 +1,83 @@ +from docutils import nodes +from sphinx.util.docutils import SphinxDirective +from sphinx.util.nodes import nested_parse_with_titles +from docutils.statemachine import ViewList +from generate_parameter_library_py.parse_yaml import ( + GenerateCode, +) +from generate_parameter_library_py.generate_markdown import ( + DefaultConfigMarkdown, + ParameterDetailMarkdown +) + +class GeneraterParameterLibraryDetails(SphinxDirective): + required_arguments = 1 + optional_arguments = 0 + + def run(self): + # get the absolute path from sphinx tree + yaml_file = self.env.relfn2path(self.arguments[0], self.env.docname)[0] + + gen_param_struct = GenerateCode("rst") + gen_param_struct.parse(yaml_file, "") + + param_details = [ + ParameterDetailMarkdown(param) + for param in gen_param_struct.declare_parameters + ] + docs = "\n".join(str(val) for val in param_details) + # print(docs) + + # Add the content one line at a time. + # Second argument is the filename to report in any warnings + # or errors, third argument is the line number. + # rst.append(docs, yaml_file, 10) + rst = ViewList() + for line in docs.splitlines(): + rst.append(line, yaml_file) + + node = nodes.section() + # necessary so that the child nodes get the right source/line set + node.document = self.state.document + nested_parse_with_titles(self.state, rst, node) + + return node.children + +class GeneraterParameterLibraryDefaultConfig(SphinxDirective): + required_arguments = 1 + optional_arguments = 0 + + def run(self): + # get the absolute path from sphinx tree + yaml_file = self.env.relfn2path(self.arguments[0], self.env.docname)[0] + + gen_param_struct = GenerateCode("rst") + gen_param_struct.parse(yaml_file, "") + auto_doc = DefaultConfigMarkdown(gen_param_struct) + docs = str(auto_doc) + # print(docs) + + # Add the content one line at a time. + # Second argument is the filename to report in any warnings + # or errors, third argument is the line number. + # rst.append(docs, yaml_file, 10) + rst = ViewList() + for line in docs.splitlines(): + rst.append(line, yaml_file) + + node = nodes.section() + # necessary so that the child nodes get the right source/line set + node.document = self.state.document + nested_parse_with_titles(self.state, rst, node) + + return node.children + +def setup(app): + app.add_directive("generate_parameter_library_details", GeneraterParameterLibraryDetails) + app.add_directive("generate_parameter_library_default", GeneraterParameterLibraryDefaultConfig) + + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/conf.py b/conf.py index 3d94110bf00..44c583fabad 100644 --- a/conf.py +++ b/conf.py @@ -19,6 +19,7 @@ from docutils.parsers.rst import Directive +sys.path.append(os.path.abspath("./_ext")) sys.path.append(os.path.abspath("./sphinx-multiversion")) # -- General configuration ------------------------------------------------- @@ -87,7 +88,12 @@ "sphinx.ext.extlinks", "sphinx.ext.ifconfig", "sphinx_copybutton", +<<<<<<< HEAD "sphinx.ext.viewcode", +======= + "sphinxcontrib.globalsubs", + "generate_parameter_library" +>>>>>>> b8bf31a (Sphinx extension for autodocs (#97)) ] # If true, `todo` and `todoList` produce output, else they produce nothing.