Skip to content

Commit ff0f708

Browse files
authored
Update dev_guide.md
1 parent 1e8938f commit ff0f708

File tree

1 file changed

+10
-10
lines changed

1 file changed

+10
-10
lines changed

docs/src/devdocs/dev_guide.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Catalyst Developer Documentation
22

3-
## Release Process
3+
## [Release Process](@id devdocs_releaseprocess)
44
Beginning with v15, Catalyst is using a new release process to try to ensure
55
continuing stability of releases. Before making a release one should
66

@@ -11,10 +11,10 @@ continuing stability of releases. Before making a release one should
1111
- Do not cap the master branch as this can prevent upstream libraries from
1212
properly testing against Catalyst, and hide breaking changes that impact
1313
Catalyst.
14-
3. Check docs build with the capped dependencies. Visually verify via checking
15-
the artifact in the doc build that the docs actually look ok (since sometimes
16-
issues can arise that do not lead to actual errors in the doc CI).
17-
4. Release via the [registration
14+
3. [Check docs build](@ref devdocs_advice_doc_inspection) with the capped dependencies.
15+
Visually verify via checking the artifact in the doc build that the docs actually
16+
look ok (since sometimes issues can arise that do not lead to actual errors in the doc CI).
17+
5. Release via the [registration
1818
issue](https://github.com/SciML/Catalyst.jl/issues/127) with the
1919
command: `@JuliaRegistrator register branch=release-15.0.0`, modifying as appropriate
2020
for the version you are releasing.
@@ -29,17 +29,17 @@ should be preferred. If the new release branch is branched from master, *it
2929
needs to ensure Project.toml caps are all ≥ to those listed in the previous
3030
Catalyst release branch*.
3131

32-
## Development advice
32+
## [Development advice](@id devdocs_advice)
3333

34-
### Checking doc builds for errors
34+
### [Checking doc builds for errors](@id devdocs_advice_doc_error_checks)
3535
When updating documentation, Catalyst will run any Julia code provided within example blocks to dynamically create figures and outputs. In addition to automatically creating these for us, it also provides an automatic check that all code in documentation is correct. Here, if any of the documentation code throws an error, the build job will fail. The documentation build job can be found at the bottom of a PRs conversation, here is an example of a failed one:
3636

3737
![Failed builddocs link](../assets/devdocs/failed_builddocs_link.png)
3838

3939
To check what errors were produced, click on the "Details" link of the job. Next, any errors can be found at the bottom of the "Build and deploy" section (which should be opened automatically).
4040

41-
### Inspecting documentation of a PR or branch
42-
When updating documentation it is typically useful to view the updated documentation in HTML format (which is the format users will see). Here, some errors are much easier to spot in html format as compared with the raw text files from which these are generated. There are two primary ways to view updated documentation, either by downloading them from the PR or by building the docs locally.
41+
### [Inspecting the built documentation of a PR or branch](@id devdocs_advice_doc_inspection)
42+
When updating documentation it is typically useful to view the updated documentation in HTML format (which is the format users will see). Here, some errors are much easier to spot in .html format as compared with the raw text files from which these are generated. There are two primary ways to view updated documentation, either by downloading them from the PR or by building the docs locally.
4343

4444
Whenever a PR to Catalyst is created, CI will create a corresponding documenter build job. If the build job passes, you can access the built documentation (which will be the new Catalyst documentation if the PR is merged) through the following steps:
4545
1. Click on "Details" in the documentation build job (at the bottom of the PR conversation tab).
@@ -51,5 +51,5 @@ To build the Catalyst documentation locally:
5151
1. Navigate to the ".julia/dev/Catalyst/docs/" folder and run the "make.jl" file using ">julia make.jl". Alternatively, open a Julia session, activate the "docs" environment, and run the file using `include("make.jl").
5252
2. Open the ".julia/dev/Catalyst/docs/build/index.html" file.
5353

54-
### Spellchecking in your code
54+
### [Spellchecking in your code](@id devdocs_advice_codespellchecker)
5555
Especially when writing documentation, but also when writing normal code, it can be useful to have a spellchecker running through your texts. While code can be copied into a spellchecker and checked there (which is still useful to check grammar), it can also be very useful to (for users of VSCode) run the [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) extension. This will automatically provide simple spell-checking for code and documentation as you write it.

0 commit comments

Comments
 (0)