diff options
author | Loïc Vital <mugulmotion@gmail.com> | 2022-10-04 17:46:29 +0300 |
---|---|---|
committer | Loïc Vital <mugulmotion@gmail.com> | 2022-10-11 10:59:33 +0300 |
commit | b2db98f128866370b631ecbca510164d7200ba56 (patch) | |
tree | fc6bcf19a68e079ec2ffa7438ee99862eb3ec57e /docs | |
parent | 243c278bccea56aaddbd7366b63fea6a4ce20456 (diff) |
[doc] sphinx documentation setup
Diffstat (limited to 'docs')
-rw-r--r-- | docs/.gitignore | 3 | ||||
-rw-r--r-- | docs/Makefile | 20 | ||||
-rw-r--r-- | docs/README.md | 18 | ||||
-rw-r--r-- | docs/make.bat | 35 | ||||
-rw-r--r-- | docs/source/_ext/fetch_md.py | 65 | ||||
-rw-r--r-- | docs/source/_templates/autosummary/module.rst | 63 | ||||
-rw-r--r-- | docs/source/api.rst | 9 | ||||
-rw-r--r-- | docs/source/changes.rst | 6 | ||||
-rw-r--r-- | docs/source/conf.py | 40 | ||||
-rw-r--r-- | docs/source/index.rst | 15 | ||||
-rw-r--r-- | docs/source/install.rst | 6 |
11 files changed, 280 insertions, 0 deletions
diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..50e5506a --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +# Sphinx +build/ +source/generated/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..d0c3cbf1 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..303059dc --- /dev/null +++ b/docs/README.md @@ -0,0 +1,18 @@ +# Documentation + +We use [Sphinx](https://www.sphinx-doc.org) to generate Meshroom's documentation. + +To install all the requirements for building the documentation, simply run: +```bash +pip install sphinx sphinx-rtd-theme myst-parser +``` + +> Note: since Sphinx will import the entire `meshroom` package, all requirements for Meshroom must also be installed + +To generate the documentation, go to the `docs` folder and run the Sphinx makefile: +```bash +cd meshroom/docs +make html +``` + +To access the documentation, simply go to `meshroom/docs/build/html` and open `index.html` in a browser. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..dc1312ab --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/source/_ext/fetch_md.py b/docs/source/_ext/fetch_md.py new file mode 100644 index 00000000..43a07930 --- /dev/null +++ b/docs/source/_ext/fetch_md.py @@ -0,0 +1,65 @@ +import os +from docutils.nodes import SparseNodeVisitor +from docutils.parsers.rst import Directive +from myst_parser.docutils_ import Parser +from myst_parser.mdit_to_docutils.base import make_document + + +class Relinker(SparseNodeVisitor): + + @staticmethod + def get_link_key(node): + link_keys = ['uri', 'refuri', 'refname'] + for key in link_keys: + if key in node.attributes.keys(): + return key + return None + + def relink(self, node, base_dir): + key = Relinker.get_link_key(node) + if key is None: + return + link = node.attributes[key] + if link.startswith('http') or link.startswith('mailto'): + return + if link.startswith('/'): + link = link[1:] + node.attributes[key] = base_dir+'/'+link + + def visit_image(self, node): + self.relink(node, os.getenv('PROJECT_DIR')) + + +class FetchMd(Directive): + + required_arguments = 2 + + def arg_path(self): + if self.arguments[0] == ':file:': + return self.arguments[1] + + def run(self): + path = os.path.abspath(os.getenv('PROJECT_DIR') + '/' + self.arg_path()) + result = [] + try: + with open(path) as file: + parser = Parser() + text = file.read() + doc = make_document(parser_cls=Parser) + parser.parse(text, doc) + relinker = Relinker(doc) + doc.walk(relinker) + result.append(doc[0]) + except FileNotFoundError: + pass + return result + + +def setup(app): + app.add_directive('fetch_md', FetchMd) + + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True + } diff --git a/docs/source/_templates/autosummary/module.rst b/docs/source/_templates/autosummary/module.rst new file mode 100644 index 00000000..635912f7 --- /dev/null +++ b/docs/source/_templates/autosummary/module.rst @@ -0,0 +1,63 @@ +{{ fullname | escape | underline}} + + +.. automodule:: {{ fullname }} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Module Attributes') }} + + .. autosummary:: + {% for item in attributes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + .. autosummary:: + {% for item in functions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :toctree: + :recursive: + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + +{% block modules %} +{% if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: +{% for item in modules %} + {{ item }} +{%- endfor %} +{% endif %} +{% endblock %} diff --git a/docs/source/api.rst b/docs/source/api.rst new file mode 100644 index 00000000..8af742bc --- /dev/null +++ b/docs/source/api.rst @@ -0,0 +1,9 @@ +Python API Reference +==================== + + +.. autosummary:: + :recursive: + :toctree: generated + + meshroom diff --git a/docs/source/changes.rst b/docs/source/changes.rst new file mode 100644 index 00000000..1b84907c --- /dev/null +++ b/docs/source/changes.rst @@ -0,0 +1,6 @@ +Release Notes +============= + + +.. fetch_md:: + :file: CHANGES.md diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 00000000..709e205a --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,40 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +import os +from pathlib import Path +import sys + +os.environ['PROJECT_DIR'] = Path('../..').resolve().as_posix() + +sys.path.append(os.path.abspath(os.getenv('PROJECT_DIR'))) +sys.path.append(os.path.abspath('./_ext')) + +project = 'Meshroom' +copyright = '2022, AliceVision Association' +author = 'AliceVision Association' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'fetch_md' +] + +templates_path = ['_templates'] +exclude_patterns = [] + + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'sphinx_rtd_theme' +html_static_path = ['_static'] diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 00000000..bd01d0c5 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,15 @@ +Welcome to meshroom's documentation! +==================================== + + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api + install + changes + + +.. fetch_md:: + :file: README.md diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 00000000..b05e1676 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,6 @@ +Install +======= + + +.. fetch_md:: + :file: INSTALL.md |