Merge pull request #656 from Fortran-FOSS-Programmers/fix-docs

Fix documentation builds on readthedocs

.readthedocs.yaml

@@ -7,21 +7,17 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-20.04
+  os: ubuntu-24.04
   tools:
-    python: "3.8"
+    python: "3.12"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
    configuration: docs/conf.py
 
-# Optionally build your docs in additional formats such as PDF
-# formats:
-#    - pdf
-
-# Optionally declare the Python requirements required to build your docs
 python:
   install:
     - method: pip
-      path: .[docs]
-  system_packages: true
+      path: .
+      extra_requirements:
+        - docs

docs/conf.py

@@ -83,4 +83,5 @@
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "markdown": ("https://python-markdown.github.io", None),
 }

ford.py

@@ -3,5 +3,5 @@
 
 from ford import run
 
-if __name__ == '__main__' :
+if __name__ == "__main__":
     run()

ford/_markdown.py

@@ -51,7 +51,6 @@ def __init__(
         aliases: Optional[Dict[str, str]] = None,
         project: Optional[Project] = None,
     ):
-
         default_extensions: List[Union[str, Extension]] = [
             "markdown_include.include",
             "markdown.extensions.codehilite",
@@ -101,11 +100,11 @@ def convert(
 
         Parameters
         ----------
-        source : str
+        source:
             Text to convert
-        context : Optional[FortranBase]
+        context:
             Current Ford object being processed
-        path : Optional[Path]
+        path:
             Current (output) path of page being processed
 
         """
@@ -155,7 +154,7 @@ def run(self, lines: List[str]) -> List[str]:
 
 
 class AliasExtension(Extension):
-    """Markdown extension to register `AliasProcessor`"""
+    """Markdown extension to register `AliasPreprocessor`"""
 
     def __init__(self, **kwargs):
         self.config = {"aliases": [{}, "List of aliases"]}
@@ -257,6 +256,7 @@ def find_child(context):
         return link
 
     def handleMatch(self, m: re.Match, data: str):  # type: ignore[override]
+        """Return the converted match, along with start and end positions"""
         return self.convert_link(m), m.start(0), m.end(0)
 
 

ford/graphs.py

@@ -1010,8 +1010,8 @@ def _create_image_file(self, filename: pathlib.Path):
     def add_nodes(self, nodes, nesting=1):
         """Add nodes and edges to this graph, based on the collection ``nodes``
 
-        Subclasses should implement `_add_node`, and optionally
-        `_extra_attributes`
+        Subclasses should implement `FortranGraph.add_node`, and optionally
+        `FortranGraph.extra_attributes`
 
         """
         hop_nodes = set()  # nodes in this hop
@@ -1028,12 +1028,12 @@ def rainbowcolour(depth, maxd):
         for i, node in enumerate(sorted(nodes)):
             colour = rainbowcolour(i, total_len)
 
-            self._add_node(hop_nodes, hop_edges, node, colour)
+            self.add_node(hop_nodes, hop_edges, node, colour)
 
         if not self.add_to_graph(hop_nodes, hop_edges, nesting):
             return
 
-        self._extra_attributes()
+        self.extra_attributes()
 
         if self._should_add_nested_nodes:
             self._add_nested_nodes(hop_nodes, nesting)
@@ -1048,15 +1048,15 @@ def _add_nested_nodes(self, hop_nodes, nesting):
         else:
             self.truncated = nesting
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         """Add a single node and its edges to this graph, typically by
         iterating over parents/children
 
         """
 
         raise NotImplementedError
 
-    def _extra_attributes(self):
+    def extra_attributes(self):
         """Add any extra attributes to the graph"""
         pass
 
@@ -1066,7 +1066,7 @@ class ModuleGraph(FortranGraph):
 
     _legend = MOD_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for nu in sorted(node.uses):
             if nu not in self.added:
                 hop_nodes.add(nu)
@@ -1077,7 +1077,7 @@ def _add_node(self, hop_nodes, hop_edges, node, colour):
                 hop_nodes.add(node.ancestor)
             hop_edges.append(_solid_edge(node, node.ancestor, colour))
 
-    def _extra_attributes(self):
+    def extra_attributes(self):
         self.dot.attr("graph", size="11.875,1000.0")
 
 
@@ -1087,7 +1087,7 @@ class UsesGraph(FortranGraph):
     _should_add_nested_nodes = True
     _legend = MOD_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for nu in sorted(node.uses):
             if nu not in self.added:
                 hop_nodes.add(nu)
@@ -1105,7 +1105,7 @@ class UsedByGraph(FortranGraph):
     _should_add_nested_nodes = True
     _legend = MOD_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for nu in sorted(getattr(node, "used_by", [])):
             if nu not in self.added:
                 hop_nodes.add(nu)
@@ -1121,7 +1121,7 @@ class FileGraph(FortranGraph):
 
     _legend = FILE_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for ne in sorted(node.efferent):
             if ne not in self.added:
                 hop_nodes.add(ne)
@@ -1134,7 +1134,7 @@ class EfferentGraph(FortranGraph):
     _should_add_nested_nodes = True
     _legend = FILE_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for ne in sorted(node.efferent):
             if ne not in self.added:
                 hop_nodes.add(ne)
@@ -1147,7 +1147,7 @@ class AfferentGraph(FortranGraph):
     _should_add_nested_nodes = True
     _legend = FILE_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for na in sorted(node.afferent):
             if na not in self.added:
                 hop_nodes.add(na)
@@ -1159,7 +1159,7 @@ class TypeGraph(FortranGraph):
 
     _legend = TYPE_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for keys in node.comp_types.keys():
             if keys not in self.added:
                 hop_nodes.add(keys)
@@ -1172,7 +1172,7 @@ def _add_node(self, hop_nodes, hop_edges, node, colour):
                 hop_nodes.add(node.ancestor)
             hop_edges.append(_solid_edge(node, node.ancestor, colour))
 
-    def _extra_attributes(self):
+    def extra_attributes(self):
         self.dot.attr("graph", size="11.875,1000.0")
 
 
@@ -1182,7 +1182,7 @@ class InheritsGraph(FortranGraph):
     _should_add_nested_nodes = True
     _legend = TYPE_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for c in node.comp_types:
             if c not in self.added:
                 hop_nodes.add(c)
@@ -1199,7 +1199,7 @@ class InheritedByGraph(FortranGraph):
     _should_add_nested_nodes = True
     _legend = TYPE_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for c in node.comp_of:
             if c not in self.added:
                 hop_nodes.add(c)
@@ -1219,7 +1219,7 @@ class CallGraph(FortranGraph):
     RANKDIR = "LR"
     _legend = CALL_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for p in sorted(node.calls):
             if p not in hop_nodes:
                 hop_nodes.add(p)
@@ -1232,7 +1232,7 @@ def _add_node(self, hop_nodes, hop_edges, node, colour):
                 hop_nodes.add(p)
             hop_edges.append(_dashed_edge(node, p, colour))
 
-    def _extra_attributes(self):
+    def extra_attributes(self):
         self.dot.attr("graph", size="11.875,1000.0")
         self.dot.attr("graph", concentrate="false")
 
@@ -1244,7 +1244,7 @@ class CallsGraph(FortranGraph):
     _should_add_nested_nodes = True
     _legend = CALL_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         for p in sorted(node.calls):
             if p not in self.added:
                 hop_nodes.add(p)
@@ -1257,7 +1257,7 @@ def _add_node(self, hop_nodes, hop_edges, node, colour):
                 hop_nodes.add(p)
             hop_edges.append(_dashed_edge(node, p, colour))
 
-    def _extra_attributes(self):
+    def extra_attributes(self):
         self.dot.attr("graph", concentrate="false")
 
 
@@ -1268,7 +1268,7 @@ class CalledByGraph(FortranGraph):
     _should_add_nested_nodes = True
     _legend = CALL_GRAPH_KEY
 
-    def _add_node(self, hop_nodes, hop_edges, node, colour):
+    def add_node(self, hop_nodes, hop_edges, node, colour):
         if isinstance(node, ProgNode):
             return
         for p in sorted(node.called_by):
@@ -1280,7 +1280,7 @@ def _add_node(self, hop_nodes, hop_edges, node, colour):
                 hop_nodes.add(p)
             hop_edges.append(_dashed_edge(p, node, colour))
 
-    def _extra_attributes(self):
+    def extra_attributes(self):
         self.dot.attr("graph", concentrate="false")
 
 

ford/md_admonition.py

@@ -32,6 +32,7 @@
     "bug": "danger",
     "history": "history",
 }
+"""Mapping of Ford note types to markdown's admonition types"""
 
 
 class AdmonitionExtension(Extension):

ford/settings.py

@@ -344,7 +344,7 @@ def convert_setting(default_type: Type, key: str, value: Any) -> Any:
         is_same_type(default_type, str) or is_same_type(default_type, Path)
     ) and isinstance(value, list):
         return "\n".join(value)
-    elif (get_origin(default_type) == dict) and not isinstance(value, dict):
+    elif (get_origin(default_type) is dict) and not isinstance(value, dict):
         resvalue = value
         if isinstance(value, str):
             resvalue = [value]

ford/sourceform.py

@@ -2131,7 +2131,7 @@ def _cleanup(self):
 
 
 class FortranInterface(FortranContainer):
-    """An `interface` block, including generic and abstract interfaces
+    """An ``interface`` block, including generic and abstract interfaces
 
     Attributes
     ----------