Skip to content

Commit 75215fd

Browse files
lily-tomkovic-DWRlily-tomkovic-DWR
committed
add documentation on documentation
1 parent 5d86540 commit 75215fd

10 files changed

+272
-0
lines changed

‎docsrc/diagrams/bds_mermaid_conventions.mmd

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
config:
3+
look: classic
4+
theme: redux
5+
layout: default
6+
---
7+
%%{
8+
init: {
9+
'theme': 'base',
10+
'themeVariables': {
11+
'primaryColor': '#fff',
12+
'primaryTextColor': '#000',
13+
'primaryBorderColor': '#002570',
14+
'lineColor': '#000',
15+
'secondaryColor': '#d1d1d1',
16+
'tertiaryColor': '#fff'
17+
}
18+
}
19+
}%%
20+
flowchart LR
21+
22+
%% files ---------------
23+
subgraph Files
24+
doc@{ shape: doc, label: "Single File"} --> docs@{ shape: docs, label: "Multiple File"}
25+
end
26+
27+
%% Workflows -----------
28+
29+
subgraph Workflows
30+
large{"Large Process
31+
(like 'Run Simulations')"}
32+
concept(["Conceptual Process
33+
(like 'Gridding')"])
34+
simple["Simple Process
35+
(like 'Run prepare_schism')"]
36+
large --> concept --> simple
37+
end
38+
39+
%% Decision/Flow --------
40+
subgraph Decision
41+
start([Event: All Inputs Ready]) --> decpt{"Decision Point (?)"}
42+
decpt -- Yes ----> actiony[Take yes-based action]
43+
decpt -- No --> actionn[Take no-based action]
44+
actionn --> reset[Reset] --> decpt
45+
end
46+
47+
%% A e1@==> B
48+
%% e1@{ animate: true }
49+
Files ~~~ Workflows ~~~ Decision
50+
51+
52+
%% Command Line prompt to produce the svg diagram
53+
%% > mmdc -i .\bds_mermaid_conventions.mmd -o ../img/bds_mermaid_conventions.svg

‎docsrc/diagrams/bds_style_template.mmd

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
config:
3+
look: classic
4+
theme: base
5+
---
6+
%%{
7+
init: {
8+
'theme': 'base',
9+
'themeVariables': {
10+
'primaryColor': '#fff',
11+
'primaryTextColor': '#000',
12+
'primaryBorderColor': '#002570',
13+
'lineColor': '#000',
14+
'secondaryColor': '#d1d1d1',
15+
'tertiaryColor': '#fff'
16+
}
17+
}
18+
}%%

‎docsrc/documentation.rst

+94
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
.. _documentation:
2+
3+
================================
4+
Documentation of BayDeltaSCHISM
5+
================================
6+
7+
Introduction
8+
-------------
9+
10+
We use the python-based html documentation generator package `Sphinx <https://www.sphinx-doc.org/en/master/>`_ to create our webpage (including this one!). It uses `reStructuredText (.rst) <https://docutils.sourceforge.io/rst.html>`_ which is a component of yet another python package `Docutils <https://docutils.sourceforge.io/index.html>`_. The reStructuredText files are written in an easy-to-read lightweight markup language. You can see how this very webpage looks in reStructuredText by looking at the source file in the GitHub repository: `docsrc/documentation.rst <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM/blob/master/docsrc/documentation.rst>`_
11+
12+
We also use a diagram visualization tool `Mermaid <https://mermaid.js.org/intro/>`_ which uses JavaScript to render Markdown-inspired text into beautiful flowcharts and diagrams.
13+
14+
And last but certainly not least, we use `Click <https://click.palletsprojects.com/en/stable/>`_ to create command line interfaces (cli) for our code. Sphinx has a plugin `sphinx-click <https://sphinx-click.readthedocs.io/en/latest/>`_ which allows for automatic documentation for our cli commands.
15+
16+
17+
Getting Started
18+
----------------
19+
.. _bds_doc:
20+
21+
Windows
22+
=========
23+
24+
There's a batch script in the BayDeltaSCHISM repository that you can use to set up your conda environment that's compatible with our documentation utilities.
25+
26+
First, clone the repository using::
27+
28+
git clone https://github.com/CADWRDeltaModeling/BayDeltaSCHISM.git
29+
30+
Then open a terminal that has conda enabled (PowerShell, Anaconda prompt, etc) and navigate to your BayDeltaSCHISM folder and type::
31+
32+
./setup_doc_env_windows.bat
33+
34+
This will create a conda enviornment called "bds_doc" using `BayDeltaSCHISM/schism_env.yml <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM/blob/master/schism_env.yml>`_, and then download a utility for generating Mermaid diagrams, and finally install the documentation dependencies of bdschism.
35+
36+
To activate the environment, simply type::
37+
38+
conda activate bds_doc
39+
40+
Linux
41+
=====
42+
43+
Guidance for Linux has yet to be documented.
44+
45+
How it works
46+
-------------
47+
48+
Local html pages
49+
================
50+
51+
Before you even start modifying or adding documentation, try activating the environment you made in :ref:`Getting Started <bds_doc>`. Then all you need to do to be able to test the documentation is navigate to BayDeltaSCHISM/docsrc and type::
52+
53+
make html
54+
55+
This will generate all of the necessary html files in order to render the webpage that is eventually hosted on GitHub (`here <https://cadwrdeltamodeling.github.io/BayDeltaSCHISM>`_). But any html files that you render locally (by running ``make html``) are just for you to see and check. You do not *need* to run ``make html`` for any of your changes to the `.rst` files to regenerate the GitHub webpage, but it's highly recommended in order to review your changes and make sure they're behaving as expected once rendered on GitHub.
56+
57+
The home page is always ``docs/index.html``. If you open that in your browser you can navigate a local version of the webpage and test the functionality of the .rst file edits you made.
58+
59+
60+
GitHub Pages
61+
==============
62+
63+
Whenever a commit is pushed to the `BayDeltaSCHISM <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM>`_ repository, a few `GitHub Actions <https://github.com/features/actions>`_ are automatically triggered.
64+
65+
The first is to render the .rst files using Sphinx and save to the `gh-pages branch of the repository <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM/tree/gh-pages>`_. This action's process is defined using the `.github/workflows/build_sphinx.yml <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM/blob/master/.github/workflows/build_sphinx.yml>`_ workflow document. You can tell that it's triggered by the "on" section of the yaml file:
66+
67+
.. code-block:: yaml
68+
:emphasize-lines: 3, 4, 5, 6
69+
70+
name: "Sphinx: Render docs"
71+
72+
on:
73+
# Runs on pushes targeting the default branch
74+
push:
75+
branches: ["main", "master"]
76+
77+
...
78+
79+
The rest of the file creates an environment (similar to the local process for :ref:`Getting Started <bds_doc>`), then runs ``make clean`` and ``make html``, then pushes those html changes to the `gh-pages branch of the repository <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM/tree/gh-pages>`_.
80+
81+
From there, a new action is triggered because the gh-pages page has been pushed to, and there's a `GitHub-configured action <https://github.com/marketplace/actions/deploy-to-github-pages>`_ that then takes the `index.html <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM/blob/gh-pages/index.html>`_ file and hosts it on our `BayDeltaSCHISM website <https://cadwrdeltamodeling.github.io/BayDeltaSCHISM>`_.
82+
83+
84+
Further Documentation Concepts
85+
------------------------------
86+
87+
.. toctree::
88+
:maxdepth: 4
89+
:titlesonly:
90+
91+
meta_doc/doc_sphinx.rst
92+
meta_doc/doc_mermaid.rst
93+
meta_doc/doc_click.rst
94+
meta_doc/doc_examples.rst

‎docsrc/img/bds_mermaid_conventions.svg

+1
Loading

‎docsrc/img/mermaid_chart_ext.png

22.5 KB
Loading

‎docsrc/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Contents
2929
getmodel
3030
learning
3131
user_guide
32+
documentation
3233
calibration
3334
help
3435
refs

‎docsrc/meta_doc/doc_click.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.. _doc_click:
2+
3+
Click Documentation Principles
4+
------------------------------

‎docsrc/meta_doc/doc_examples.rst

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.. _doc_examples:
2+
3+
Documenation examples
4+
----------------------

‎docsrc/meta_doc/doc_mermaid.rst

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
.. _doc_mermaid:
2+
3+
Mermaid Chart Principles
4+
=========================
5+
6+
The environment that you can create by following the :ref:`Getting Started <bds_doc>` section allows for you to generate standalone .svg files that you can then reference in .rst files.
7+
8+
BayDeltaSCHISM Standards
9+
------------------------
10+
11+
Symbols
12+
`````````
13+
14+
We follow the conventions of `Mermaid Syntax <https://mermaid.js.org/syntax/flowchart.html>`_ for the most part. But for process flows, files and decisions, we generally follow:
15+
16+
.. raw:: html
17+
:file: ../img/bds_mermaid_conventions.svg
18+
19+
The raw .mmd file for the above chart is in `docsrc/diagrams/bds_mermaid_conventions.mmd <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM/blob/master/docsrc/diagrams/bds_mermaid_conventions.mmd>`_
20+
21+
Style
22+
```````
23+
24+
You can add the following pre-amble to your .mmd charts to use a consistent style across pages:
25+
26+
.. code-block:: md
27+
28+
---
29+
config:
30+
look: classic
31+
theme: base
32+
---
33+
%%{
34+
init: {
35+
'theme': 'base',
36+
'themeVariables': {
37+
'primaryColor': '#fff',
38+
'primaryTextColor': '#000',
39+
'primaryBorderColor': '#002570',
40+
'lineColor': '#000',
41+
'secondaryColor': '#d1d1d1',
42+
'tertiaryColor': '#fff'
43+
}
44+
}
45+
}%%
46+
47+
This is found in `docsrc/diagrams/bds_style_template.mmd <https://github.com/CADWRDeltaModeling/BayDeltaSCHISM/blob/master/docsrc/diagrams/bds_style_template.mmd>`_
48+
49+
50+
VS Code plugin
51+
--------------
52+
53+
The easiest plugin to use with Mermaid charts is `Mermaid Chart <https://marketplace.visualstudio.com/items/?itemName=MermaidChart.vscode-mermaid-chart>`_ by mermaidchart.com
54+
55+
.. figure:: ../img/mermaid_chart_ext.png
56+
:class: with-border
57+
:width: 70%
58+
:align: center
59+
60+
VS Code Mermaid Chart extension
61+
62+
This plugin allows you to preview your .mmd documents in another VS Code window.

‎docsrc/meta_doc/doc_sphinx.rst

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
.. _doc_sphinx:
2+
3+
Sphinx Documentation Principles
4+
================================
5+
6+
First, you can review Sphinx's reStructuredText Primer `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. But some basics that are super useful:
7+
8+
Headings order
9+
---------------
10+
11+
Underneath each heading you can repeat one of the following characters under the entire heading text:
12+
13+
``= - ` : . ' " ~ ^ _ * + #``
14+
15+
This is also the order that the headers are used, and this affects the way a table of contents is rendered and which sections are nested where.
16+
17+
Ex:
18+
19+
.. code-block:: rst
20+
21+
Sphinx Documenation Principles
22+
==============================
23+
24+
Headings order
25+
---------------
26+
27+
This creates the headings above. Note that the header characters extend to the full extent of the text above them. If they are short they will not work as section headers.
28+
29+
BayDeltaSCHISM Specifics
30+
-------------------------
31+
32+
Any .rst files that relate to the `User Guide <https://cadwrdeltamodeling.github.io/BayDeltaSCHISM/user_guide.html>`_ are held in the ``docsrc/topics`` folder. **No other .rst files are found there.**
33+
34+
Similarly all documentation files are found in the ``docsrc/meta_doc`` folder.
35+

0 commit comments

Comments
 (0)