From f3bed081bda887d2c9df953fbdbe30d01829940e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Vital?= <mugulmotion@gmail.com>
Date: Fri, 21 Oct 2022 13:42:34 +0200
Subject: [PATCH] [docs] commenting custom extensions

---
 .readthedocs.yaml                |  7 ++++---
 docs/source/_ext/fetch_md.py     | 14 ++++++++++++++
 docs/source/_ext/meshroom_doc.py | 13 +++++++++++++
 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: