Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation_style_guide.md #735

Merged
merged 2 commits into from
Aug 1, 2024
Merged

Update documentation_style_guide.md #735

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a2224bb
Update documentation_style_guide.md
ljhwang Jun 1, 2024
faab668
Update doc/sphinx/developer_manual/contributing_to_the_documentation/…
MFraters Aug 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions ...developer_manual/contributing_to_the_documentation/documentation_style_guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
Documentation style guide
=========================

Not only are there many ways to style the documents, there are also many ways with sphinx to reach the same output. To attempt to unify the style of the documentation and the documentation code, this page contains some general styling recommendations.
Not only are there many ways to style the documents, there are also many ways with Sphinx to reach the same output. To attempt to unify the style of the documentation and the documentation code, this page contains some general styling recommendations.

# Page titles

Expand All @@ -14,7 +14,7 @@ The page label should always be a path, separated by colons (`:`) in the followi

# Including advanced elements

When possible, the use of colons (`:`) should be preferred over the use of grave accents (\`) when creating advanced elements such as todo notes, figures, code blocks, or tables. This means that:
When possible, the use of colons (`:`) should be preferred over the use of grave accents (\`) when creating advanced elements such as todo notes, figures, code blocks or tables. This means that:

::::{code-block} md
:::{note}
Expand All @@ -32,11 +32,11 @@ My Note

# Including World Builder files

When including a world builder file, it is important to be able to focus on the parts which are important, while also enabling the reader to see the surrounding context and the whole file. Furthermore, the user should have the capability to run the models themselves and get the same output as shown. To standardize this the following structure is strongly encouraged.
When including a World Builder file, it is important to be able to focus on the parts which are important, while also enabling the reader to see the surrounding context and the whole file. Furthermore, the user should have the capability to run the models themselves and get the same output as shown. To standardize this the following structure is strongly encouraged.

1. The world builder file and a corresponding grid file need to be stored separately, either in the cookbook, or in the _static directory.
2. The use of a tab-set with a tab with important lines and a tab with the full world builder file, highlighting important lines.
3. Adding at least a link to the world builder file and a grid file to visualize it, preferably also a link to a `.pvtu` file which allows to get the same output as the figure, if present.
1. The World Builder file and a corresponding grid file need to be stored separately, either in the cookbook, or in the _static directory.
2. The use of a tab-set with a tab with important lines and a tab with the full World Builder file, highlighting important lines.
3. Adding at least a link to the World Builder file and a grid file to visualize it, preferably also a link to a `.pvtu` file which allows to get the same output as the figure, if present.
4. Add a figure of the output.

Below is an example code block.
Expand Down
Loading