[docs] commenting custom extensions

.readthedocs.yaml

@@ -5,11 +5,12 @@
 # Required
 version: 2
 
-# Build documentation in the docs/ directory with Sphinx
+# Build HTML documentation with Sphinx
 sphinx:
+  builder: html
   configuration: docs/source/conf.py
 
-# Optionally declare the Python requirements required to build your docs
+# Python requirements
 python:
   install:
     - requirements: requirements.txt

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

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

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: