Docs and Docstrings (#383)

* Move docs around and use automatic name from md * Fix all seeds in GP tests * Autodocs block + explainer * Some tidying up * Comments -> docstrings in BBCode * Fix outdated docstring * Some more tidying up + refactoring * Improve docstring for binary zero_tangent * More tidying up * Bump patch version * Fix broken doctest * Fix docs build * Improve wording * Fix coverage * Improve coverage
compintell · Nov 21, 2024 · eaf1fb8 · eaf1fb8 · willtebbutt · Nov 21, 2024
1 parent 19dae92
commit eaf1fb8
Show file tree

Hide file tree

Showing 24 changed files with 468 additions and 244 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "Mooncake"
 uuid = "da2b9cff-9c12-43a0-ae48-6db2b0edb7d6"
 authors = ["Will Tebbutt, Hong Ge, and contributors"]
-version = "0.4.47"
+version = "0.4.48"
 
 [deps]
 ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"

diff --git a/docs/make.jl b/docs/make.jl
@@ -19,6 +19,9 @@ makedocs(
                 ),
             )
         ),
+        size_threshold_ignore=[
+            joinpath("developer_documentation", "internal_docstrings.md"),
+        ],
     ),
     modules=[Mooncake],
     checkdocs=:none,
@@ -28,20 +31,21 @@ makedocs(
     pages = [
         "Mooncake.jl" => "index.md",
         "Understanding Mooncake.jl" => [
-            "Introduction" => "understanding_intro.md",
-            "Algorithmic Differentiation" => "algorithmic_differentiation.md",
-            "Mooncake.jl's Rule System" => "mathematical_interpretation.md",
+            joinpath("understanding_mooncake", "introduction.md"),
+            joinpath("understanding_mooncake", "algorithmic_differentiation.md"),
+            joinpath("understanding_mooncake", "rule_system.md"),
         ],
         "Utilities" => [
-            "Tools for Rules" => "tools_for_rules.md",
-            "Debug Mode" => "debug_mode.md",
-            "Debugging and MWEs" => "debugging_and_mwes.md",
+            joinpath("utilities", "tools_for_rules.md"),
+            joinpath("utilities", "debug_mode.md"),
+            joinpath("utilities", "debugging_and_mwes.md"),
         ],
         "Developer Documentation" => [
-            "Running Tests Locally" => "running_tests_locally.md",
-            "Developer Tools" => "developer_tools.md",
+            joinpath("developer_documentation", "running_tests_locally.md"),
+            joinpath("developer_documentation", "developer_tools.md"),
+            joinpath("developer_documentation", "internal_docstrings.md"),
         ],
-        "Known Limitations" => "known_limitations.md",
+        "known_limitations.md",
     ]
 )
 

diff --git a/docs/src/developer_tools.md → ...eveloper_documentation/developer_tools.md b/docs/src/developer_tools.md → ...eveloper_documentation/developer_tools.md
diff --git a/docs/src/developer_documentation/internal_docstrings.md b/docs/src/developer_documentation/internal_docstrings.md
@@ -0,0 +1,11 @@
+# Internal Docstrings
+
+Docstrings listed here are _not_ part of the public Mooncake.jl interface.
+Consequently, they can change between non-breaking changes to Mooncake.jl without warning.
+
+The purpose of this is to make it easy for developers to find docstrings straightforwardly via the docs, as opposed to having to ctrl+f through Mooncake.jl's source code, or looking at the docstrings via the Julia REPL.
+
+```@autodocs; canonical=false
+Modules = [Mooncake]
+Public = false
+```
diff --git a/docs/src/running_tests_locally.md → ...er_documentation/running_tests_locally.md b/docs/src/running_tests_locally.md → ...er_documentation/running_tests_locally.md
diff --git a/docs/src/algorithmic_differentiation.md → ...g_mooncake/algorithmic_differentiation.md b/docs/src/algorithmic_differentiation.md → ...g_mooncake/algorithmic_differentiation.md
diff --git a/docs/src/understanding_intro.md → ...rc/understanding_mooncake/introduction.md b/docs/src/understanding_intro.md → ...rc/understanding_mooncake/introduction.md
@@ -1,4 +1,4 @@
-# Mooncake.jl and Reverse-Mode AD
+# Introduction
 
 The point of Mooncake.jl is to perform reverse-mode algorithmic differentiation (AD).
 The purpose of this section is to explain _what_ precisely is meant by this, and _how_ it can be interpreted mathematically.

diff --git a/docs/src/mathematical_interpretation.md → ...src/understanding_mooncake/rule_system.md b/docs/src/mathematical_interpretation.md → ...src/understanding_mooncake/rule_system.md
diff --git a/docs/src/debug_mode.md → docs/src/utilities/debug_mode.md b/docs/src/debug_mode.md → docs/src/utilities/debug_mode.md
diff --git a/docs/src/debugging_and_mwes.md → docs/src/utilities/debugging_and_mwes.md b/docs/src/debugging_and_mwes.md → docs/src/utilities/debugging_and_mwes.md
diff --git a/docs/src/tools_for_rules.md → docs/src/utilities/tools_for_rules.md b/docs/src/tools_for_rules.md → docs/src/utilities/tools_for_rules.md
diff --git a/src/Mooncake.jl b/src/Mooncake.jl
@@ -68,8 +68,8 @@ include("stack.jl")
 
 include(joinpath("interpreter", "contexts.jl"))
 include(joinpath("interpreter", "abstract_interpretation.jl"))
-include(joinpath("interpreter", "bbcode.jl"))
 include(joinpath("interpreter", "ir_utils.jl"))
+include(joinpath("interpreter", "bbcode.jl"))
 include(joinpath("interpreter", "ir_normalisation.jl"))
 include(joinpath("interpreter", "zero_like_rdata.jl"))
 include(joinpath("interpreter", "s2s_reverse_mode_ad.jl"))

diff --git a/src/fwds_rvs_data.jl b/src/fwds_rvs_data.jl
@@ -901,9 +901,9 @@ Useful for implementation getfield-like rules for mutable structs, pointers, dic
 increment_rdata!!(t::T, r) where {T} = tangent(fdata(t), increment!!(rdata(t), r))::T
 
 """
-    zero_tangent(p, ::NoFData)
-
+    zero_tangent(primal, fdata)
 
+Equivalent to `tangent(fdata, rdata(zero_tangent(primal)))`.
 """
 zero_tangent(p, ::NoFData) = zero_tangent(p)
 

diff --git a/src/interpreter/abstract_interpretation.jl b/src/interpreter/abstract_interpretation.jl
@@ -61,7 +61,11 @@ MooncakeInterpreter() = MooncakeInterpreter(DefaultCtx)
 
 context_type(::MooncakeInterpreter{C}) where {C} = C
 
-# Globally cached interpreter. Should only be accessed via `get_interpreter`.
+"""
+    const GLOBAL_INTERPRETER
+
+Globally cached interpreter. Should only be accessed via `get_interpreter`.
+"""
 const GLOBAL_INTERPRETER = Ref(MooncakeInterpreter())
 
 """