Cross-referencing and cleaning

Author: mzecc

TODO.md

@@ -55,9 +55,9 @@
 #     fh.writelines("* [example_fgen_basic](home.html)")
 
 # Remove the ford files (which were just copied)
-shutil.rmtree(REPO_ROOT / FORD_OUTPUT_DIR)
+# shutil.rmtree(REPO_ROOT / FORD_OUTPUT_DIR)
 
 # Put back the gitkeep file
 gitkeep = REPO_ROOT / FORD_OUTPUT_DIR / ".gitkeep"
-gitkeep.parent.mkdir()
+# gitkeep.parent.mkdir()
 gitkeep.touch()

docs/gen_fortran_api.py

@@ -18,7 +18,6 @@
 # Here we show how you can make your docs via notebooks.
 
 # %% editable=true slideshow={"slide_type": ""}
-from example_fgen_basic.operations import add_two
 
 # %% editable=true slideshow={"slide_type": ""}
-add_two(3.2, 4.3)
+c = 1 + 2

docs/how-to-guides/run-code-in-a-notebook.py

@@ -18,9 +18,9 @@ module m_error_v_creation
     function create_error(inv) result(err)
         !! Create an error
         !!
-        !! If an odd number is supplied, the error code is no error (TODO: cross-ref).
-        !! If an even number is supplied, the error code is 1.
-        !! If a negative number is supplied, the error code is 2.
+        !> If an odd number is supplied, the error code is [[m_error_v:NO_ERROR_CODE(variable)]].
+        !> If an even number is supplied, the error code is `1`.
+        !> If a negative number is supplied, the error code is `2`.
 
         integer, intent(in) :: inv
         !! Value to use to create the error
@@ -44,9 +44,9 @@ end function create_error
     function create_errors(invs, n) result(errs)
         !! Create a number of errors
         !!
-        !! If an odd number is supplied, the error code is no error (TODO: cross-ref).
-        !! If an even number is supplied, the error code is 1.
-        !! If a negative number is supplied, the error code is 2.
+        !> If an odd number is supplied, the error code is [[m_error_v:NO_ERROR_CODE(variable)]].
+        !> If an even number is supplied, the error code is `1`.
+        !> If a negative number is supplied, the error code is `2`.
 
         integer, dimension(n), intent(in) :: invs
         !! Values to use to create the error

src/example_fgen_basic/error_v/creation.f90

@@ -1,5 +1,5 @@
 """
-Wrappers of `m_error_v_creation` [TODO think about naming and x-referencing]
+Wrappers of [`m_error_v_creation`](/fortran-api/module/m_error_v_creation.html)
 
 At the moment, all written by hand.
 We will auto-generate this in future.
@@ -41,7 +41,6 @@ def create_error(inv: int) -> ErrorV:
         Input value
 
         If odd, the error code is
-        [NO_ERROR_CODE][example_fgen_basic.error_v.NO_ERROR_CODE].
         If even, the error code is 1.
         If a negative number is supplied, the error code is 2.
 

src/example_fgen_basic/error_v/creation.py

@@ -25,13 +25,12 @@ module m_error_v_creation_w
 contains
 
     function create_error(inv) result(res_instance_index)
-        !! Wrapper around `m_error_v_creation.create_error` (TODO: x-ref)
+        !> Wrapper around `m_error_v_creation.create_error` ([[m_error_v_creation(module):create_error(function)]])
 
         integer, intent(in) :: inv
-        !! Input value to use to create the error
-        !!
-        !! See docstring of `m_error_v_creation.create_error` for details.
-        !! [TODO: x-ref]
+        !> Input value to use to create the error
+        !>
+        !> See docstring of [[m_error_v_creation(module):create_error(function)]] for details.
 
         integer :: res_instance_index
         !! Instance index of the result
@@ -56,13 +55,12 @@ function create_error(inv) result(res_instance_index)
     end function create_error
 
     function create_errors(invs, n) result(res_instance_indexes)
-        !! Wrapper around `m_error_v_creation.create_errors` (TODO: x-ref)
+        !> Wrapper around `m_error_v_creation.create_errors` ([[m_error_v_creation(module):create_errors(function)]])
 
         integer, dimension(n), intent(in) :: invs
         !! Input value to use to create the error
         !!
-        !! See docstring of `m_error_v_creation.create_error` for details.
-        !! [TODO: x-ref]
+        !> See docstring of [[m_error_v_creation(module):create_errors(function)]] for details.
 
         integer, intent(in) :: n
         !! Number of values to create

src/example_fgen_basic/error_v/creation_wrapper.f90

@@ -23,6 +23,7 @@ module m_error_v
         character(len=128) :: message = ""
         !! Error message
         ! TODO: think about making the message allocatable to handle long messages
+        !character(len=:), allocatable :: message --- would not work?
 
         ! TODO: think about adding idea of critical
         ! (means you can stop but also unwind errors and traceback along the way)
@@ -34,7 +35,7 @@ module m_error_v
 
         private
 
-        procedure, public:: build, finalise
+        procedure, public :: build, finalise
         ! get_res sort of not needed (?)
         ! get_err sort of not needed (?)
 
@@ -68,7 +69,7 @@ subroutine build(self, code, message)
         integer, intent(in) :: code
         !! Error code
         !!
-        !! Use [TODO: figure out xref] `NO_ERROR_CODE` if there is no error
+        !> Use [[m_error_v:NO_ERROR_CODE(variable)]] if there is no error.
 
         character(len=*), optional, intent(in) :: message
         !! Error message

src/example_fgen_basic/error_v/error_v.f90

@@ -1,5 +1,5 @@
 """
-Python equivalent of the Fortran `ErrorV` class [TODO: x-refs]
+Python equivalent of the Fortran [ErrorV](/fortran-api/type/errorv.html) class.
 
 At the moment, all written by hand.
 We will auto-generate this in future.
@@ -46,8 +46,8 @@ def from_instance_index(cls, instance_index: int) -> ErrorV:
 
         Returns
         -------
-        :
-            Initialised index
+        ErrorV
+            Python instance containing Fortran data
         """
         # Different wrapping strategies are needed
 

src/example_fgen_basic/error_v/error_v.py

@@ -1,4 +1,4 @@
-!> Manager of `ErrorV` (TODO: xref) across the Fortran-Python interface
+!> Manager of [[m_error_v(module)]] across the Fortran-Python interface
 !>
 !> Written by hand here.
 !> Generation to be automated in future (including docstrings of some sort).
@@ -12,9 +12,9 @@ module m_error_v_manager
     type(ErrorV), dimension(:), allocatable :: instance_array
     logical, dimension(:), allocatable :: instance_available
 
-    ! TODO: think about ordering here, alphabetical probably easiest
-    public :: build_instance, finalise_instance, get_available_instance_index, get_instance, set_instance_index_to, &
-              ensure_instance_array_size_is_at_least
+    public :: build_instance, ensure_instance_array_size_is_at_least, finalise_instance, &
+              get_available_instance_index, get_instance, set_instance_index_to
+
 
 contains
 
@@ -143,7 +143,7 @@ subroutine ensure_instance_array_size_is_at_least(n)
             ! Race conditions ?
             instance_available = .true.
 
-        elseif (size(instance_available) < n) then
+        else if (size(instance_available) < n) then
 
             allocate(tmp_instances(n))
             tmp_instances(1:size(instance_array)) = instance_array

src/example_fgen_basic/error_v/error_v_manager.f90

@@ -1,4 +1,4 @@
-!> Wrapper for interfacing `m_error_v` with Python
+!> Wrapper for interfacing  [[m_error_v(module)::ErrorV(type)]] with Python
 !>
 !> Written by hand here.
 !> Generation to be automated in future (including docstrings of some sort).
@@ -27,9 +27,9 @@ subroutine build_instance(code, message, instance_index)
         !! Build an instance
 
         integer, intent(in) :: code
-        !! Error code
+        !> Error code
         !!
-        !! Use [TODO: figure out xref] `NO_ERROR_CODE` if there is no error
+        !> Use [[m_error_v:NO_ERROR_CODE(variable)]] if there is no error
 
         character(len=*), optional, intent(in) :: message
         !! Error message