Skip to content

Commit ab4ae5e

Browse files
mzeccmzecc
committed
FORD-MkDocs integration: First iteration
1 parent 7230260 commit ab4ae5e

7 files changed

Lines changed: 78 additions & 47 deletions

File tree

‎Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,12 +69,15 @@ test: ## run the tests (re-installs the package every time so you might want to
6969
.PHONY: docs
7070
docs: ## build the docs
7171
@echo "Building Fortran docs"
72-
uv run ford ford_example.md
72+
uv run --no-sync ford ford_example.md
7373
@echo "Building documentation"
7474
uv run --no-sync mkdocs build
7575

7676
.PHONY: docs-strict
7777
docs-strict: ## build the docs strictly (e.g. raise an error on warnings, this most closely mirrors what we do in the CI)
78+
@echo "Building Fortran docs"
79+
uv run --no-sync ford ford_example.md
80+
@echo "Building documentation"
7881
uv run --no-sync mkdocs build --strict
7982

8083
.PHONY: docs-serve

‎docs/NAVIGATION.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,5 @@ See https://oprypin.github.io/mkdocs-literate-nav/
1313
- [Dependency pinning and testing](further-background/dependency-pinning-and-testing.md)
1414
- [Development](development.md)
1515
- [API reference](api/example_fgen_basic/)
16-
- [Fortran API](fortran-api/index.md)
16+
- [Fortran API](fortran-api/index.html)
1717
- [Changelog](changelog.md)

‎docs/development.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,35 @@ Try and keep your merge requests as small as possible
3131
This makes life much easier for reviewers
3232
which allows contributions to be accepted at a faster rate.
3333

34+
## Using uv with a compiled package
35+
36+
Using uv with a compiled package is a bit more painful.
37+
Whenever you do `uv run` or `uv sync` or similar,
38+
uv tries to install the compiled package as an editable package.
39+
This can then cause issues on later calls to `uv run` or `uv sync`
40+
as having compiled packages as editable packages doesn't really work
41+
(you get errors like
42+
`ImportError: re-building the <package-name> meson-python editable wheel package failed`).
43+
The way around this is to:
44+
45+
1. use the `--no-editable` flag with `uv sync`
46+
so that uv doesn't do an editable install
47+
1. use the `--no-sync` flag with `uv run`
48+
(and any other command that takes this flag)
49+
so that `uv` doesn't try and re-build packages
50+
1. use the `--reinstall-package` flag with `uv run`
51+
whenever you want to be sure that the latest changes
52+
will be used for running a command
53+
(yes, this makes running things slower,
54+
but slower and reliable is better than broken)
55+
56+
We include these flags in our `Makefile` and GitHub workflows
57+
if you want to see them in use.
58+
59+
If you forget and run `uv run ...` in your terminal.
60+
The easiest solution seems to be to delete your virtual environment entirely and start again.
61+
We haven't found a way to get out of an accidental editable install.
62+
3463
## Language
3564

3665
We use British English for our development.

‎docs/fortran-api/lists/files.html‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -95,15 +95,30 @@ <h1>Source Files</h1>
9595
<g id="file~~graph~~FileGraph" class="graph" transform="scale(1 1) rotate(0) translate(4 28)">
9696
<title>file~~graph~~FileGraph</title>
9797
<polygon fill="white" stroke="transparent" points="-4,4 -4,-28 481,-28 481,4 -4,4"/>
98-
<!-- sourcefile~get_wavelength.f90 -->
98+
<!-- sourcefile~kind_parameters.f90 -->
9999
<g id="file~~graph~~FileGraph_node1" class="node">
100+
<title>sourcefile~kind_parameters.f90</title>
101+
<g id="a_file~~graph~~FileGraph_node1"><a xlink:href=".././sourcefile/kind_parameters.f90.html" xlink:title="kind_parameters.f90">
102+
<polygon fill="#f0ad4e" stroke="#f0ad4e" points="477,-24 354,-24 354,0 477,0 477,-24"/>
103+
<text text-anchor="middle" x="415.5" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">kind_parameters.f90</text>
104+
</a>
105+
</g>
106+
</g>
107+
<!-- sourcefile~get_wavelength.f90 -->
108+
<g id="file~~graph~~FileGraph_node2" class="node">
100109
<title>sourcefile~get_wavelength.f90</title>
101-
<g id="a_file~~graph~~FileGraph_node1"><a xlink:href=".././sourcefile/get_wavelength.f90.html" xlink:title="get_wavelength.f90">
110+
<g id="a_file~~graph~~FileGraph_node2"><a xlink:href=".././sourcefile/get_wavelength.f90.html" xlink:title="get_wavelength.f90">
102111
<polygon fill="#f0ad4e" stroke="#f0ad4e" points="318,-24 201,-24 201,0 318,0 318,-24"/>
103112
<text text-anchor="middle" x="259.5" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">get_wavelength.f90</text>
104113
</a>
105114
</g>
106115
</g>
116+
<!-- sourcefile~kind_parameters.f90&#45;&gt;sourcefile~get_wavelength.f90 -->
117+
<g id="file~~graph~~FileGraph_edge1" class="edge">
118+
<title>sourcefile~kind_parameters.f90&#45;&gt;sourcefile~get_wavelength.f90</title>
119+
<path fill="none" stroke="#000000" d="M353.64,-12C345.39,-12 336.88,-12 328.52,-12"/>
120+
<polygon fill="#000000" stroke="#000000" points="328.41,-8.5 318.41,-12 328.41,-15.5 328.41,-8.5"/>
121+
</g>
107122
<!-- sourcefile~get_wavelength_wrapper.f90 -->
108123
<g id="file~~graph~~FileGraph_node3" class="node">
109124
<title>sourcefile~get_wavelength_wrapper.f90</title>
@@ -119,21 +134,6 @@ <h1>Source Files</h1>
119134
<path fill="none" stroke="#000000" d="M200.71,-12C192.56,-12 184.01,-12 175.4,-12"/>
120135
<polygon fill="#000000" stroke="#000000" points="175.29,-8.5 165.29,-12 175.29,-15.5 175.29,-8.5"/>
121136
</g>
122-
<!-- sourcefile~kind_parameters.f90 -->
123-
<g id="file~~graph~~FileGraph_node2" class="node">
124-
<title>sourcefile~kind_parameters.f90</title>
125-
<g id="a_file~~graph~~FileGraph_node2"><a xlink:href=".././sourcefile/kind_parameters.f90.html" xlink:title="kind_parameters.f90">
126-
<polygon fill="#f0ad4e" stroke="#f0ad4e" points="477,-24 354,-24 354,0 477,0 477,-24"/>
127-
<text text-anchor="middle" x="415.5" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">kind_parameters.f90</text>
128-
</a>
129-
</g>
130-
</g>
131-
<!-- sourcefile~kind_parameters.f90&#45;&gt;sourcefile~get_wavelength.f90 -->
132-
<g id="file~~graph~~FileGraph_edge1" class="edge">
133-
<title>sourcefile~kind_parameters.f90&#45;&gt;sourcefile~get_wavelength.f90</title>
134-
<path fill="none" stroke="#000000" d="M353.64,-12C345.39,-12 336.88,-12 328.52,-12"/>
135-
<polygon fill="#000000" stroke="#000000" points="328.41,-8.5 318.41,-12 328.41,-15.5 328.41,-8.5"/>
136-
</g>
137137
</g>
138138
</svg>
139139
</div><div><a type="button" class="graph-help" data-toggle="modal" href="#graph-help-text">Help</a></div><div class="modal fade" id="graph-help-text" tabindex="-1" role="dialog"><div class="modal-dialog modal-lg" role="document"><div class="modal-content"><div class="modal-header"><button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button><h4 class="modal-title" id="-graph-help-label">Graph Key</h4></div><div class="modal-body">

‎docs/fortran-api/lists/modules.html‎

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -105,36 +105,36 @@ <h1>Modules</h1>
105105
</a>
106106
</g>
107107
</g>
108-
<!-- module~m_get_wavelength_w -->
108+
<!-- module~m_get_wavelength -->
109109
<g id="module~~graph~~ModuleGraph_node2" class="node">
110-
<title>module~m_get_wavelength_w</title>
111-
<g id="a_module~~graph~~ModuleGraph_node2"><a xlink:href=".././module/m_get_wavelength_w.html" xlink:title="m_get_wavelength_w">
112-
<polygon fill="#337ab7" stroke="#337ab7" points="413,-24 287,-24 287,0 413,0 413,-24"/>
113-
<text text-anchor="middle" x="350" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">m_get_wavelength_w</text>
110+
<title>module~m_get_wavelength</title>
111+
<g id="a_module~~graph~~ModuleGraph_node2"><a xlink:href=".././module/m_get_wavelength.html" xlink:title="m_get_wavelength">
112+
<polygon fill="#337ab7" stroke="#337ab7" points="251,-24 139,-24 139,0 251,0 251,-24"/>
113+
<text text-anchor="middle" x="195" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">m_get_wavelength</text>
114114
</a>
115115
</g>
116116
</g>
117-
<!-- module~m_get_wavelength -->
117+
<!-- module~m_get_wavelength&#45;&gt;module~kind_parameters -->
118+
<g id="module~~graph~~ModuleGraph_edge1" class="edge">
119+
<title>module~m_get_wavelength&#45;&gt;module~kind_parameters</title>
120+
<path fill="none" stroke="#000000" stroke-dasharray="5,2" d="M138.89,-12C130.5,-12 121.81,-12 113.31,-12"/>
121+
<polygon fill="#000000" stroke="#000000" points="113.07,-8.5 103.07,-12 113.07,-15.5 113.07,-8.5"/>
122+
</g>
123+
<!-- module~m_get_wavelength_w -->
118124
<g id="module~~graph~~ModuleGraph_node3" class="node">
119-
<title>module~m_get_wavelength</title>
120-
<g id="a_module~~graph~~ModuleGraph_node3"><a xlink:href=".././module/m_get_wavelength.html" xlink:title="m_get_wavelength">
121-
<polygon fill="#337ab7" stroke="#337ab7" points="251,-24 139,-24 139,0 251,0 251,-24"/>
122-
<text text-anchor="middle" x="195" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">m_get_wavelength</text>
125+
<title>module~m_get_wavelength_w</title>
126+
<g id="a_module~~graph~~ModuleGraph_node3"><a xlink:href=".././module/m_get_wavelength_w.html" xlink:title="m_get_wavelength_w">
127+
<polygon fill="#337ab7" stroke="#337ab7" points="413,-24 287,-24 287,0 413,0 413,-24"/>
128+
<text text-anchor="middle" x="350" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">m_get_wavelength_w</text>
123129
</a>
124130
</g>
125131
</g>
126132
<!-- module~m_get_wavelength_w&#45;&gt;module~m_get_wavelength -->
127-
<g id="module~~graph~~ModuleGraph_edge1" class="edge">
133+
<g id="module~~graph~~ModuleGraph_edge2" class="edge">
128134
<title>module~m_get_wavelength_w&#45;&gt;module~m_get_wavelength</title>
129135
<path fill="none" stroke="#000000" stroke-dasharray="5,2" d="M286.77,-12C278.42,-12 269.83,-12 261.42,-12"/>
130136
<polygon fill="#000000" stroke="#000000" points="261.29,-8.5 251.29,-12 261.29,-15.5 261.29,-8.5"/>
131137
</g>
132-
<!-- module~m_get_wavelength&#45;&gt;module~kind_parameters -->
133-
<g id="module~~graph~~ModuleGraph_edge2" class="edge">
134-
<title>module~m_get_wavelength&#45;&gt;module~kind_parameters</title>
135-
<path fill="none" stroke="#000000" stroke-dasharray="5,2" d="M138.89,-12C130.5,-12 121.81,-12 113.31,-12"/>
136-
<polygon fill="#000000" stroke="#000000" points="113.07,-8.5 103.07,-12 113.07,-15.5 113.07,-8.5"/>
137-
</g>
138138
</g>
139139
</svg>
140140
</div><div><a type="button" class="graph-help" data-toggle="modal" href="#graph-help-text">Help</a></div><div class="modal fade" id="graph-help-text" tabindex="-1" role="dialog"><div class="modal-dialog modal-lg" role="document"><div class="modal-content"><div class="modal-header"><button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button><h4 class="modal-title" id="-graph-help-label">Graph Key</h4></div><div class="modal-body">

‎docs/fortran-api/lists/procedures.html‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -94,21 +94,21 @@ <h1>Procedures</h1>
9494
<g id="call~~graph~~CallGraph" class="graph" transform="scale(1 1) rotate(0) translate(4 28)">
9595
<title>call~~graph~~CallGraph</title>
9696
<polygon fill="white" stroke="transparent" points="-4,4 -4,-28 234,-28 234,4 -4,4"/>
97-
<!-- proc~get_wavelength -->
97+
<!-- proc~get_wavelength~2 -->
9898
<g id="call~~graph~~CallGraph_node1" class="node">
99-
<title>proc~get_wavelength</title>
100-
<g id="a_call~~graph~~CallGraph_node1"><a xlink:href=".././proc/get_wavelength.html" xlink:title="get_wavelength">
101-
<polygon fill="#d94e8f" stroke="#d94e8f" points="230,-24 133,-24 133,0 230,0 230,-24"/>
102-
<text text-anchor="middle" x="181.5" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">get_wavelength</text>
99+
<title>proc~get_wavelength~2</title>
100+
<g id="a_call~~graph~~CallGraph_node1"><a xlink:href=".././proc/get_wavelength~2.html" xlink:title="get_wavelength">
101+
<polygon fill="#d94e8f" stroke="#d94e8f" points="97,-24 0,-24 0,0 97,0 97,-24"/>
102+
<text text-anchor="middle" x="48.5" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">get_wavelength</text>
103103
</a>
104104
</g>
105105
</g>
106-
<!-- proc~get_wavelength~2 -->
106+
<!-- proc~get_wavelength -->
107107
<g id="call~~graph~~CallGraph_node2" class="node">
108-
<title>proc~get_wavelength~2</title>
109-
<g id="a_call~~graph~~CallGraph_node2"><a xlink:href=".././proc/get_wavelength~2.html" xlink:title="get_wavelength">
110-
<polygon fill="#d94e8f" stroke="#d94e8f" points="97,-24 0,-24 0,0 97,0 97,-24"/>
111-
<text text-anchor="middle" x="48.5" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">get_wavelength</text>
108+
<title>proc~get_wavelength</title>
109+
<g id="a_call~~graph~~CallGraph_node2"><a xlink:href=".././proc/get_wavelength.html" xlink:title="get_wavelength">
110+
<polygon fill="#d94e8f" stroke="#d94e8f" points="230,-24 133,-24 133,0 230,0 230,-24"/>
111+
<text text-anchor="middle" x="181.5" y="-9.6" font-family="Helvetica,sans-Serif" font-size="10.50" fill="white">get_wavelength</text>
112112
</a>
113113
</g>
114114
</g>

‎ford_example.md‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@ project: Example fgen - basic
33
author: Me
44
output_dir: docs/fortran-api
55
src_dir: src
6-
markdown: true
76
graph: true
87
---
98

0 commit comments

Comments
 (0)