From 43a6eda3050babe19665362e5ad50d79d8d504a2 Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Sun, 18 Feb 2024 18:17:12 -0800 Subject: [PATCH 1/6] add info for docs dev/build/vis --- docs/index.md | 2 + docs/meta.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 docs/meta.md diff --git a/docs/index.md b/docs/index.md index 36584c99bf7c..d518adfc865a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -3,8 +3,10 @@ The documentation for the components of E3SM is found here. ## Components + - [EAM](./EAM/index.md) - [EAMxx](./EAMxx/index.md) - [ELM](./ELM/index.md) - [MOSART](./MOSART/index.md) +Please see [Developing Docs](./meta.md) to learn about developing documentation for E3SM. diff --git a/docs/meta.md b/docs/meta.md new file mode 100644 index 000000000000..4a9d8f2526f9 --- /dev/null +++ b/docs/meta.md @@ -0,0 +1,102 @@ +# Developing Docs for E3SM + +The E3SM source code includes the documentation of the model in text files stored along with source code in the main repository. Please follow project guidelines to develop on feature branches. + +Our documentation is written in Markdown language. See [Basic writing and formatting syntax - GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) to get started. + +## Local development environment + +Just like you compile and test your Fortran before committing it, you should "compile" and view your documentation before committing and pushing the branch. Unlike compiling and running the model, the documentation can be easily built and displayed on your laptop. Here are two way to do that. + +### Virtual environment (venv) + +You can create a local python virtual environment for the doc building packages (which is a one-time setup). On your local laptop in your home directory, create a python virtual environment called “mkdocsenv” for example `python3 -m venv mkdocsenv`. Now you can enter the environment with `source mkdocsenv/bin/activate`. To build and visualize the docs, please install the python packages needed: + +```shell +pip install mkdocs-material mkdocs-monorepo-plugin pymdown-extensions mdutils mkdocs-bibtex +``` + +At any time, you can leave the environment by typing: `deactivate`. + +The creation of mkdocsenv and the pip install commands only have to be done once on each platform you want to do documentation development. + +Installing a python package in a virtual environment keeps it from being installed system wide which is good practice and also useful if you don’t have permissions to install system-level packages. + +### Conda environment + +The same python environment above can be achieve with conda. To do so, create a conda environment with a `conda create -n e3sm_docs mkdocs-material pymdown-extensions mkdocs-monorepo-plugin mdutils mkdocs-bibtex`, and then `conda activate e3sm_docs` to use the environment. + +## Local building and testing + +Activate your virtual environment that you made in the above step with either `source mkdocsenv/bin/activate` or `conda activate e3sm_docs`. Change directory to the top level E3SM directory and see if you can build the current docs by typing + +```shell +mkdocs build +``` + +Note that EAMxx docs use an automated routine to populate the namelist parameters. In order to avoid warnings on this step, please ensure you have a copy of the CIME submodule inside your main repo. Then, you will be able to build with `mkdocs build --strict --verbose` (to convert any warning into an error, which we use in the PR checking). + +To View the docs locally in your browser with the built-in server, you can type + +```shell +mkdocs serve +``` + +Follow the instructions output by the above command to display in your browser. To exist the server, hit Control-C. + +An alternative to mkdocs serve is to access to the docs directly without serving them through a URL. To achieve this, one could you `file:///E3SM_ROOT/site/index.html` in a modern browser like Chrome (in place of a URL). In this case, E3SM_ROOT is the full path to the clone E3SM repository on your local machine. One could directly go to other pages as needed using the same method (e.g., `file:///E3SM_ROOT/site/EAM/index.html`). + +As you edit the documentation, rerun the `mkdocs build` command and refresh the website in your browser. The output of `mkdocs build` will tell you if you have a syntax error in your markdown files. The website in your browser will let you know if it looks as you intended. + +## Documentation organization + +The documentation for a model should be stored within that model's source code directory. + +The first file needed is mkdocs.yml which should be in `E3SM/components/`. See `E3SM/components/eam/mkdocs.yml` for an example: + +```yaml +site_name: EAM + +nav: + - Introduction: 'index.md' + - Users's Guide: user-guide/index.md + - Developers's Guide: dev-guide/index.md + - Technical Guide: tech-guide/index.md +``` + +The "site_name" is the keyword used in the `E3SM/docs/index.md` file to reference all the model's documentation. (That file must be edited when adding a new model’s documentation.) + +All other files should be stored under `E3SM/components//docs` + +The basic structure under "docs" is + +```shell +index.md - top level introductory text and links to main sections +dev-guide/ - subdir for development guide +tech-guide/ - subidr for technical guide +user-guide/ - subdir for user guide +``` + +Each of the sub-dirs should also have an `index.md` file to organize their content. + +## Files and sections + +A subsection of your documentation should be contained entirely in a single file. Short sections can be grouped in to one file. + +Equation numbering and references to equations are local to an individual markdown file. + +## Figures + +When you start adding figures to your documentation, keep in mind that binary files can lead to repo size bloat IF they change a lot so don’t commit a figure to the repo until you are confident its the near-final version. + +Figures should be in png format and under 500 pixels on the longest side. + +Keep figures in the same directory as the Markdown file referencing them. + +## Markdown style guide + +To help with maintainability, everyone is encouraged to follow best practices when it comes to writing markdown files. For example, popular IDEs support [`markdownlint`](https://github.com/DavidAnson/markdownlint). + +## Automated preview during PRs + +When you submit a PR, we have an automated process to build and test the docs (with `--strict --verbose`) and to preview them directly in the PR. An automated bot will leave a comment with a URL for you to review the docs. From c3d44b9d474ee7e6e360f0d3989bcf32c444db6f Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Sun, 18 Feb 2024 18:17:41 -0800 Subject: [PATCH 2/6] add link in main nav --- mkdocs.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yaml b/mkdocs.yaml index 27fafbeba4d0..d4ab21a8558f 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -2,6 +2,7 @@ site_name: E3SM nav: - Introduction: 'index.md' + - Developing Docs: 'meta.md' - Components: '*include ./components/*/mkdocs.yml' theme: From 622725198a5eb9ace11e6bdc1a44879b20653117 Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Sun, 18 Feb 2024 18:19:26 -0800 Subject: [PATCH 3/6] add link to e3sm docs --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 84eb15d8e186..63448dc525c9 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,9 @@ DOI: [10.11578/E3SM/dc.20230110.5](http://dx.doi.org/10.11578/E3SM/dc.20230110.5 Please visit the [project website](https://e3sm.org) or our [Confluence site](https://acme-climate.atlassian.net/wiki/spaces/DOC/overview) for further details. -For questions about the model, use [Github Discussions](https://github.com/E3SM-Project/E3SM/discussions) +For questions about the model, use [Github Discussions](https://github.com/E3SM-Project/E3SM/discussions). + +See our Github-hosted documentation at [https://e3sm-project.github.io/E3SM/](https://e3sm-project.github.io/E3SM/). Table of Contents -------------------------------------------------------------------------------- From d6ed0306df6dd49cb563ea67d9171cd1a515b09c Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Sun, 18 Feb 2024 18:31:44 -0800 Subject: [PATCH 4/6] improve the presentation in docs meta --- docs/meta.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/docs/meta.md b/docs/meta.md index 4a9d8f2526f9..3532727e7bd8 100644 --- a/docs/meta.md +++ b/docs/meta.md @@ -59,9 +59,9 @@ site_name: EAM nav: - Introduction: 'index.md' - - Users's Guide: user-guide/index.md - - Developers's Guide: dev-guide/index.md - - Technical Guide: tech-guide/index.md + - Users Guide: 'user-guide/index.md' + - Developer Guide: 'dev-guide/index.md' + - Technical Guide: 'tech-guide/index.md' ``` The "site_name" is the keyword used in the `E3SM/docs/index.md` file to reference all the model's documentation. (That file must be edited when adding a new model’s documentation.) @@ -70,12 +70,10 @@ All other files should be stored under `E3SM/components//docs` The basic structure under "docs" is -```shell -index.md - top level introductory text and links to main sections -dev-guide/ - subdir for development guide -tech-guide/ - subidr for technical guide -user-guide/ - subdir for user guide -``` +- `index.md`: top level introductory text and links to main sections +- `dev-guide/`: subdir for development guide +- `tech-guide/`: subidr for technical guide +- `user-guide/`: subdir for user guide Each of the sub-dirs should also have an `index.md` file to organize their content. From a8a2d9ce7e890879d12d456f498dc89fbbeedea9 Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Mon, 19 Feb 2024 11:08:37 -0800 Subject: [PATCH 5/6] add link to confluence page instead --- README.md | 2 - docs/index.md | 2 +- docs/meta.md | 100 -------------------------------------------------- mkdocs.yaml | 2 +- 4 files changed, 2 insertions(+), 104 deletions(-) delete mode 100644 docs/meta.md diff --git a/README.md b/README.md index 63448dc525c9..6cdaf05bff40 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,6 @@ for further details. For questions about the model, use [Github Discussions](https://github.com/E3SM-Project/E3SM/discussions). -See our Github-hosted documentation at [https://e3sm-project.github.io/E3SM/](https://e3sm-project.github.io/E3SM/). - Table of Contents -------------------------------------------------------------------------------- - [Quick Start](#quickstart) diff --git a/docs/index.md b/docs/index.md index d518adfc865a..07a587974691 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,4 +9,4 @@ The documentation for the components of E3SM is found here. - [ELM](./ELM/index.md) - [MOSART](./MOSART/index.md) -Please see [Developing Docs](./meta.md) to learn about developing documentation for E3SM. +Please see [Developing Docs](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/3924787306/Developing+Documentation) to learn about developing documentation for E3SM. diff --git a/docs/meta.md b/docs/meta.md deleted file mode 100644 index 3532727e7bd8..000000000000 --- a/docs/meta.md +++ /dev/null @@ -1,100 +0,0 @@ -# Developing Docs for E3SM - -The E3SM source code includes the documentation of the model in text files stored along with source code in the main repository. Please follow project guidelines to develop on feature branches. - -Our documentation is written in Markdown language. See [Basic writing and formatting syntax - GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) to get started. - -## Local development environment - -Just like you compile and test your Fortran before committing it, you should "compile" and view your documentation before committing and pushing the branch. Unlike compiling and running the model, the documentation can be easily built and displayed on your laptop. Here are two way to do that. - -### Virtual environment (venv) - -You can create a local python virtual environment for the doc building packages (which is a one-time setup). On your local laptop in your home directory, create a python virtual environment called “mkdocsenv” for example `python3 -m venv mkdocsenv`. Now you can enter the environment with `source mkdocsenv/bin/activate`. To build and visualize the docs, please install the python packages needed: - -```shell -pip install mkdocs-material mkdocs-monorepo-plugin pymdown-extensions mdutils mkdocs-bibtex -``` - -At any time, you can leave the environment by typing: `deactivate`. - -The creation of mkdocsenv and the pip install commands only have to be done once on each platform you want to do documentation development. - -Installing a python package in a virtual environment keeps it from being installed system wide which is good practice and also useful if you don’t have permissions to install system-level packages. - -### Conda environment - -The same python environment above can be achieve with conda. To do so, create a conda environment with a `conda create -n e3sm_docs mkdocs-material pymdown-extensions mkdocs-monorepo-plugin mdutils mkdocs-bibtex`, and then `conda activate e3sm_docs` to use the environment. - -## Local building and testing - -Activate your virtual environment that you made in the above step with either `source mkdocsenv/bin/activate` or `conda activate e3sm_docs`. Change directory to the top level E3SM directory and see if you can build the current docs by typing - -```shell -mkdocs build -``` - -Note that EAMxx docs use an automated routine to populate the namelist parameters. In order to avoid warnings on this step, please ensure you have a copy of the CIME submodule inside your main repo. Then, you will be able to build with `mkdocs build --strict --verbose` (to convert any warning into an error, which we use in the PR checking). - -To View the docs locally in your browser with the built-in server, you can type - -```shell -mkdocs serve -``` - -Follow the instructions output by the above command to display in your browser. To exist the server, hit Control-C. - -An alternative to mkdocs serve is to access to the docs directly without serving them through a URL. To achieve this, one could you `file:///E3SM_ROOT/site/index.html` in a modern browser like Chrome (in place of a URL). In this case, E3SM_ROOT is the full path to the clone E3SM repository on your local machine. One could directly go to other pages as needed using the same method (e.g., `file:///E3SM_ROOT/site/EAM/index.html`). - -As you edit the documentation, rerun the `mkdocs build` command and refresh the website in your browser. The output of `mkdocs build` will tell you if you have a syntax error in your markdown files. The website in your browser will let you know if it looks as you intended. - -## Documentation organization - -The documentation for a model should be stored within that model's source code directory. - -The first file needed is mkdocs.yml which should be in `E3SM/components/`. See `E3SM/components/eam/mkdocs.yml` for an example: - -```yaml -site_name: EAM - -nav: - - Introduction: 'index.md' - - Users Guide: 'user-guide/index.md' - - Developer Guide: 'dev-guide/index.md' - - Technical Guide: 'tech-guide/index.md' -``` - -The "site_name" is the keyword used in the `E3SM/docs/index.md` file to reference all the model's documentation. (That file must be edited when adding a new model’s documentation.) - -All other files should be stored under `E3SM/components//docs` - -The basic structure under "docs" is - -- `index.md`: top level introductory text and links to main sections -- `dev-guide/`: subdir for development guide -- `tech-guide/`: subidr for technical guide -- `user-guide/`: subdir for user guide - -Each of the sub-dirs should also have an `index.md` file to organize their content. - -## Files and sections - -A subsection of your documentation should be contained entirely in a single file. Short sections can be grouped in to one file. - -Equation numbering and references to equations are local to an individual markdown file. - -## Figures - -When you start adding figures to your documentation, keep in mind that binary files can lead to repo size bloat IF they change a lot so don’t commit a figure to the repo until you are confident its the near-final version. - -Figures should be in png format and under 500 pixels on the longest side. - -Keep figures in the same directory as the Markdown file referencing them. - -## Markdown style guide - -To help with maintainability, everyone is encouraged to follow best practices when it comes to writing markdown files. For example, popular IDEs support [`markdownlint`](https://github.com/DavidAnson/markdownlint). - -## Automated preview during PRs - -When you submit a PR, we have an automated process to build and test the docs (with `--strict --verbose`) and to preview them directly in the PR. An automated bot will leave a comment with a URL for you to review the docs. diff --git a/mkdocs.yaml b/mkdocs.yaml index d4ab21a8558f..aaeefb4c81f0 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -2,7 +2,7 @@ site_name: E3SM nav: - Introduction: 'index.md' - - Developing Docs: 'meta.md' + - 'Developing Docs': 'https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/3924787306/Developing+Documentation' - Components: '*include ./components/*/mkdocs.yml' theme: From a9ea0fdba46d1c747dc918912f550fd4ddc4745e Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Mon, 19 Feb 2024 19:37:32 -0800 Subject: [PATCH 6/6] add link to github-hosted docs --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 6cdaf05bff40..63448dc525c9 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,8 @@ for further details. For questions about the model, use [Github Discussions](https://github.com/E3SM-Project/E3SM/discussions). +See our Github-hosted documentation at [https://e3sm-project.github.io/E3SM/](https://e3sm-project.github.io/E3SM/). + Table of Contents -------------------------------------------------------------------------------- - [Quick Start](#quickstart)