From ec6c157de0ab2c43e39f4b1a877d036ac3f96a03 Mon Sep 17 00:00:00 2001 From: Sunniva Indrehus Date: Fri, 4 Jun 2021 14:11:19 +0200 Subject: [PATCH 1/7] :sparkles: New content file. Related to #16 --- content/index.rst | 1 + content/wrf-ctsm.md | 3 +++ 2 files changed, 4 insertions(+) create mode 100644 content/wrf-ctsm.md diff --git a/content/index.rst b/content/index.rst index 6302150..f479760 100644 --- a/content/index.rst +++ b/content/index.rst @@ -29,6 +29,7 @@ but rather offer some guidelines of best practices for running and developing CT get.md run.md spinup.md + wrf-ctsm.md wishlist.md tools.md in-code-documentation.md diff --git a/content/wrf-ctsm.md b/content/wrf-ctsm.md new file mode 100644 index 0000000..4151a5c --- /dev/null +++ b/content/wrf-ctsm.md @@ -0,0 +1,3 @@ +# WRF-CTSM + +Here we will put our documentation which contains details for WRF-CTSM \ No newline at end of file From cc5ce5f06e834e03f9364458cec9d22b1ebc17f5 Mon Sep 17 00:00:00 2001 From: Sunniva Indrehus Date: Fri, 4 Jun 2021 14:15:32 +0200 Subject: [PATCH 2/7] :fire: Removed unwanted template files --- content/gh-pages.md | 65 ----- content/img/gh-pages.svg | 445 ------------------------------- content/in-code-documentation.md | 183 ------------- content/index.rst | 11 +- content/rtd.md | 138 ---------- content/sphinx.md | 364 ------------------------- content/summary.md | 52 ---- content/tools.md | 170 ------------ content/wishlist.md | 187 ------------- content/writing-readme-files.md | 168 ------------ 10 files changed, 1 insertion(+), 1782 deletions(-) delete mode 100644 content/gh-pages.md delete mode 100644 content/img/gh-pages.svg delete mode 100644 content/in-code-documentation.md delete mode 100644 content/rtd.md delete mode 100644 content/sphinx.md delete mode 100644 content/summary.md delete mode 100644 content/tools.md delete mode 100644 content/wishlist.md delete mode 100644 content/writing-readme-files.md diff --git a/content/gh-pages.md b/content/gh-pages.md deleted file mode 100644 index 4332f09..0000000 --- a/content/gh-pages.md +++ /dev/null @@ -1,65 +0,0 @@ -(gh-pages)= - -# Hosting websites/homepages on GitHub Pages - -```{questions} -- How to serve a website/homepage using GitHub -``` - -## Hosting websites/homepages on GitHub Pages - -You can host your personal homepage or group webpage -or project website on GitHub using -[GitHub Pages](https://pages.github.com/). - -[GitLab](https://about.gitlab.com/features/pages/) and -[Bitbucket](https://confluence.atlassian.com/bitbucket/publishing-a-website-on-bitbucket-cloud-221449776.html) -also offer a very similar solution. - -Unless you need user authentication or a sophisticated database behind your website, -[GitHub Pages](https://pages.github.com/) can be a very nice alternative -to running your own web servers. - -This is how all -[https://coderefinery.org](https://coderefinery.org) -material is hosted. - ---- - -```{figure} img/gh-pages.svg -:alt: Scheme that describes how branch names end up websites - -Scheme that describes how branch names end up websites. -``` - ---- - -```{challenge} Exercise: Your own github page -- Deploy own website reusing a template: - - Follow the steps from GitHub Pages . - The documentation there is very good so there is no need for us to duplicate the screenshots - - Select "Project site" - - Select "Choose a theme" (for instance "Minimal") - - Click "Select theme" - - Adjust the README.md and commit - - Browse your page on `http://username.github.io/repository` (adjust "username" and "repository") -- Make a change to the repository after the webpage has been deployed for the first time -- Please wait few minutes and then verify that the change shows up on the website -``` - -```{callout} Real-life examples -- Research Software Hour (built using [Zola](https://www.getzola.org/)) - - [Source](https://raw.githubusercontent.com/ResearchSoftwareHour/researchsoftwarehour.github.io/main/content/about.md) - - Result: -- This lesson (built using [Sphinx](https://www.sphinx-doc.org/) - and [MyST](https://myst-parser.readthedocs.io/) - and [sphinx-lesson](https://coderefinery.github.io/sphinx-lesson/)) - - [Source](https://raw.githubusercontent.com/coderefinery/documentation/main/content/gh-pages.md) - - Result: this page -``` - -```{discussion} -- You can use HTML directly or another static site generator if you prefer - to not use the default [Jekyll](https://jekyllrb.com/). -- It is no problem to use a custom domain instead of `*.github.io`. -``` diff --git a/content/img/gh-pages.svg b/content/img/gh-pages.svg deleted file mode 100644 index d9b2846..0000000 --- a/content/img/gh-pages.svg +++ /dev/null @@ -1,445 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - organizational website - https://github.com/myorganization/myorganization.github.io - https://myorganization.github.io - personal homepage - https://github.com/myuser/myuser.github.io - https://myuser.github.io - - project website - https://github.com/myorganization/myproject - https://myorganization.github.io/myproject - https://github.com/myuser/myproject - https://myuser.github.io/myproject - - - - - - - (the main branch) - (generated URL of the site) - (the main branch) - (generated URL of the site) - (the gh-pages branch) - (generated URL of the site) - (the gh-pages branch) - (generated URL of the site) - - diff --git a/content/in-code-documentation.md b/content/in-code-documentation.md deleted file mode 100644 index e6b85bb..0000000 --- a/content/in-code-documentation.md +++ /dev/null @@ -1,183 +0,0 @@ -(in-code-documentation)= - -# In-code documentation - -```{questions} -- What can I do to make my code more easily understandable? -- What information should go into comments? -- What are docstrings and what information should go into docstrings? -``` - -```{objectives} -- Write docstrings according to best practices -- Know where and when to put comments -``` - -In this episode we will learn how to write good documentation inside your code. - - -## Writing good comments - -````{challenge} Exercise: Comments -Let's take a look at two example comments (comments in python start with `#`): - -**Comment A** -```python -# Now we check if temperature is larger then -50: -if temperature > -50: - print('do something') -``` - -**Comment B** -```python -# We regard temperatures below -50 degrees as measurement errors -if temperature > -50: - print('do something') -``` -Which of these comments is best? Can you explain why? -```` -```{solution} Solution -Comment A describes **what** happens in this piece of code, -whereas comment B describes **why** this piece of code is there, i.e. its **purpose**. -Comments in the form of B are much more useful, comments of form A are redundant and we should avoid them. -``` - -````{callout} -Do not use comments for: - -**Keeping zombie code** -```python -# Do not run this code!: -# if temperature > 0: -# print('It is warm') -``` -Instead: just remove the code, you can always find it back in a previous version of your code in git. - -**Replacing git** -```python -# removed on August 5 -# if() ... -# Now it connects to the API with o-auth2, updated 05/05/2016 -``` -Instead: use git to keep track of different versions of your code. -```` - -## Writing docstrings in python - -Let's look at the following function: -```python -def mean_temperature(data): - temperatures = data['Air temperature (degC)'] - return sum(temperatures)/len(temperatures) -``` -It computes the mean temperature for a given dataset. -How can we make it clearer what this function does and how to use it? - -We can add a **docstring** (the string in between the two `"""`): -```python -def mean_temperature(data): - """ - Get the mean temperature - - Args: - data (pandas.DataFrame): A pandas dataframe with air temperature measurements. - - Returns: - The mean air temperature (float) - """ - temperatures = data['Air temperature (degC)'] - return float(sum(temperatures)/len(temperatures)) -``` -A docstring is a structured comment associated to a segment of code (i.e. function or class) - -Good docstrings describe: -* What the function does -* What goes in (including the type of the input variables) -* What goes out (including the return type) - -In python there are several styles that describe how docstrings should be formatted. -Here we use [Google style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html). - -Python parses docstrings, for example calling the `help` function will display it: -```python -help(mean_temperature) -``` -Python will print this help text: -``` -Help on function mean_temperature in module __main__: - -mean_temperature(data) - Get the mean temperature - - Args: - data (pandas.DataFrame): A pandas dataframe with air temperature measurements. - - Returns: - The mean air temperature (float) -``` - -It is common to write docstrings for functions, classes, and modules. - - -````{callout} Script docstrings -You can also add a **structured** docstring at the top of a script to document what the script does and how to run it. -```python -"""Prints information about the mean air temperature. - -Usage: - ./temperature.py - -Author: - Sven van der Burg - 2021-03-2021 -""" -``` -```` - -````{callout} Small effort, large gain. -Writing docstrings makes you generate your documentation as you are generating the code! -```` - -````{challenge} Exercise: Adding in-code documentation -Update this code snippet so it is well-documented: -```python -import pandas as pd - -def x(a, print_columns=False): - b = pd.read_excel(a) - column_headers = list(b.columns.values) - if print_columns: - print("\n".join(column_headers)) - return column_headers -``` -```` - -````{solution} -```python -import pandas as pd - -def get_spreadsheet_columns(file_loc, print_columns=False): - """Gets and prints the spreadsheet's header columns - Args: - file_loc (str): The file location of the spreadsheet - print_columns (bool, optional) : A flag used to print the columns to the console (default is False) - Returns: - a list of strings used that are the header columns - """ - file_data = pd.read_excel(file_loc) - column_headers = list(file_data.columns.values) - if print_columns: - print("\n".join(column_headers)) - return column_headers -``` -```` - -````{callout} Naming **is** documentation. -Giving explicit, descriptive names to your code segments (functions, classes, variables) already provides very useful -and important documentation. In practice you will find that for simple functions it is unnecessary to add a docstring -when the function name and variable names already give enough information. -```` - -````{keypoints} -- Comments should describe the why for your code not the what. -- Writing docstrings is an easy way to write documentation while you type code. -```` diff --git a/content/index.rst b/content/index.rst index f479760..823346a 100644 --- a/content/index.rst +++ b/content/index.rst @@ -30,16 +30,7 @@ but rather offer some guidelines of best practices for running and developing CT run.md spinup.md wrf-ctsm.md - wishlist.md - tools.md - in-code-documentation.md - writing-readme-files.md - sphinx.md - rtd.md - gh-pages.md - summary.md - - + .. toctree:: :maxdepth: 1 :caption: Reference diff --git a/content/rtd.md b/content/rtd.md deleted file mode 100644 index 0003f6a..0000000 --- a/content/rtd.md +++ /dev/null @@ -1,138 +0,0 @@ -# Deploying Sphinx documentation to Read the Docs - -```{objectives} -- Create a basic workflow which you can take home and adapt for your project. -``` - -## [Read the Docs](https://readthedocs.org) - -- Runs Sphinx and converts RST or Markdown to HTML and PDF and hosts them for you -- Equations and images no problem -- Layout can be styled -- Many projects use [Read the Docs](https://readthedocs.org) as their main site -- It is no problem to serve using your own URL `http://myproject.org` instead of `http://myproject.readthedocs.io` - -### Typical Read the Docs workflow - -- Host source code with documentation sources on a public Git repository. -- Each time you `git push` to the repository, a `post-receive` hook triggers - Read the Docs to rebuild the documentation. -- Read the Docs then clones the repository, runs Sphinx, - and rebuilds HTML and PDF. -- No problem to build several branches (versions) of your documentation. - ---- - -## Exercise - -``````{challenge} Exercise: Deploy Sphinx documentation to Read the Docs -In this exercise we will fork an example repository on GitHub/GitLab and -deploy it to Read the Docs. The example project contains a script for -counting the frequency distribution of words in a given file and some -documentation generated using Sphinx. For bigger projects, we can have -more source files. - -We will use GitHub/GitLab for this exercise but it will also work with any Git repository with public read access. - -`````{tabs} - ````{tab} GitHub - - **Step 1:** Go to the [word-count project template](https://github.com/coderefinery/word-count/generate) - on GitHub and fork it to your namespace. - ```` - - ````{tab} GitLab - - **Step 1:** Import the example project to GitLab: - - Visit - - Select "Repo by URL" button - - Git repository URL is https://github.com/coderefinery/word-count.git - - Select "Public" - - Click "Create project" - ```` -````` - -**Clone the repository** - -The repository contains following two folders, among few other files and folders: -- **source** folder contains the source code -- **doc** folder contains the Sphinx documentation - -The doc folder contains the Sphinx configuration file (`conf.py`) and the index file (`index.rst`) and some contents (other RST files). -The `conf.py` file has been adjusted to be able to autogenerate documentation from sources. - - -**Build HTML pages locally** - -Inside the cloned repository, build the documentation and verify the result in your browser: - -```console -$ sphinx-build doc _build -``` - -**Test HTML pages links** - -Inside the cloned repository, check the integrity of all internal and external links: - -```console -$ sphinx-build doc -W -b linkcheck -d _build/doctrees _build/html -``` - -**Step 2:** Enable the project on [Read the Docs](https://readthedocs.org) - -**Import a project to Read the Docs by connecting to GitHub or GitLab** - -- Log into [Read the Docs](https://readthedocs.org) and visit your [dashboard](https://readthedocs.org/dashboard/) -- Click "Import a Project" -- Select "Connect to GitHub" or "Connect to GitLab", and choose the word-count repository - (if you don't see this check your [connections](https://readthedocs.org/accounts/social/connections/)) -- Rename the project to a unique name (e.g. "youruser-word-count") -- Click "Next" - -**Verify the result** - -That's it! Your site should now be live on -http://youruser-word-count.readthedocs.io (replace project name). -Note that if your Git repo name contained underscores, they get converted to hyphens. - -**Verify refreshing the documentation** - -Finally, make some changes to your documentation -- Add documentation related to other functions -- Prerequisites and how to use the program -- Rules for contribution -- Some example results (figures, tables, ...) -- Commit and push them, and verify that the documentation website refreshes after your changes (can take few seconds or a minute) -`````` - -```{callout} Do not add the generated build directory to your repository -The `_build` directory is generated locally with the command `sphinx-build -doc _build` and allows you to check the content locally but it should not be -part of the Git repository. We recommend to add `_build` to `.gitignore` to -prevent you from accidentally adding files below `_build` to the Git -repository. -``` - - -## Alternatives to Read the Docs - -Instead of using Read the Docs to host your documentation, you can host your own Sphinx server. -If you want to know more about it, look at: -- [https://docs.readthedocs.io/en/latest/install.html](https://docs.readthedocs.io/en/latest/install.html) -- [https://pypi.org/project/sphinx-autobuild/](https://pypi.org/project/sphinx-autobuild/) -- [https://pypi.org/project/sphinx-server/](https://pypi.org/project/sphinx-server/) - -You can also build Sphinx using GitHub Actions or GitLab CI -([example workflow for building this lesson](https://github.com/coderefinery/documentation/blob/main/.github/workflows/sphinx.yml)). - - -## Migrating your own documentation to Sphinx/ Read the Docs - -- First convert your documentation to RST using [Pandoc](https://pandoc.org) -- Create a file `index.rst` which lists all other RST files and provides the - table of contents. -- Add a `conf.py` file. You can generate a starting point for `conf.py` and - `index.rst` with `sphinx-quickstart`, or you can take the examples in this - lesson as inspiration. -- Test building the documentation locally with `sphinx-build`. -- Once this works, enable the project on Read the Docs and try to push a change to your documentation. diff --git a/content/sphinx.md b/content/sphinx.md deleted file mode 100644 index 88850a1..0000000 --- a/content/sphinx.md +++ /dev/null @@ -1,364 +0,0 @@ -(sphinx)= - -# Sphinx and reStructuredText - -```{objectives} -- Create example Sphinx documentation and learn some RST along the way. -``` - -## Group exercise: Build Sphinx documentation using RST - -We will take the first steps in creating documentation using Sphinx, and learn some -RST syntax along the way. - -- Our goal in this episode is to build HTML pages locally on our computers. -- In the next episode we will learn how to deploy the documentation to a cloud service - upon every `git push`. -- Please write your questions in the collaborative HackMD document so that we can answer - them and discuss them together after the group sessions. - -```{discussion} This lesson is built with Sphinx -- [Source code](https://raw.githubusercontent.com/coderefinery/documentation/main/content/sphinx.md) -- Try to compare the source code and the result side by side -- However, note that in this example we have used Markdown whereas in the following we will - demonstrate reStructuredText which is more typical in combination with Sphinx -``` - -````{callout} Prerequisites: Check whether we have the software we need - -Before we start, make sure that Sphinx is part of your Python installation or -Conda environment. - -Test Sphinx installation within Python: - -```console -$ python --version - -Python 3.7.0 -``` - -```console -$ sphinx-build --version - -sphinx-build 3.5.4 -``` - -```console -$ python -c "import sphinx_rtd_theme" - -(no output) -``` - -Test Sphinx tool installation: - -```console -$ sphinx-quickstart --version - -sphinx-quickstart 3.5.4 -``` - -The the above commands produce an error -instead of printing versions (the precise versions are not too important) -e.g. command not found or ModuleNotFoundError -please follow our -[installation instructions](https://coderefinery.github.io/installation/python/#installing-required-packages). -```` - -````{challenge} Exercise 1: Generate the basic documentation template - -Create a directory for the example documentation, step into it, and inside -generate the basic documentation template: - -```console -$ mkdir doc-example -$ cd doc-example -$ sphinx-quickstart -``` - -The quickstart utility will ask you some questions. For this exercise, you can go -with the default answers except to specify a project name, author name, and project release: - -``` -Separate source and build directories (y/n) [n]: -Project name: -Author name(s): -Project release [0.1]: 0.1 -Project language [en]: -``` - -A couple of files and directories are created: - -| File/directory | Contents | -| -------------- | -------- | -| conf.py | Documentation configuration file | -| index.rst | Main file list other RST files to parse | -| _build/ | Directory where docs are built (you can decide the name) | -| _templates/ | Your own HTML templates | -| _static/ | Static files (images, styles, etc.) copied to output directory on build | -| Makefile | Makefile to build documentation using make | -| make.bat | Makefile to build documentation using make (Windows) | - -`Makefile` and `make.bat` (for Windows) are build scripts that wrap the sphinx commands, but -we will be doing it explicitly. - -Let's have a look at the `index.rst` file, which is the main file of your documentation: - -```rst -.. myproject documentation master file, created by - sphinx-quickstart on Tue May 11 18:38:22 2021. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to myproject's documentation! -===================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` -``` - -- We will not use the `Indices and tables` section now, so remove it and everything below. -- The top four lines, starting with `..`, are a comment. -- The next lines are the table of contents. We can add content below: - -```rst -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - feature-a.rst -``` -A common gotcha with directives is that **the first line of the content must be indented to the same level as the options (i.e., :maxdepth)**. - -Let's create the file `feature-a.rst` which `index.rst` refers to: - -```rst -Some Feature A -============== - -Subsection ----------- - -Exciting documentation in here. -Let's make a list (empty surrounding lines required): - -- item 1 - - - nested item 1 - - nested item 2 - -- item 2 -- item 3 -``` - -We now build the site: - -```console -$ ls - -_build _static _templates conf.py feature-a.rst index.rst - -$ sphinx-build . _build - -Running Sphinx v3.5.4 -loading pickled environment... done -building [mo]: targets for 0 po files that are out of date -building [html]: targets for 1 source files that are out of date -updating environment: 1 added, 1 changed, 0 removed -reading sources... [100%] index -looking for now-outdated files... none found -pickling environment... done -checking consistency... done -preparing documents... done -writing output... [100%] index -generating indices... genindex -writing additional pages... search -copying static files... done -copying extra files... done -dumping search index in English (code: en) ... done -dumping object inventory... done -build succeeded. - -$ ls _build - -_sources _static feature-a.html genindex.html index.html objects.inv search.html searchindex.js -``` - -Now open the file `_build/index.html` in your browser by: - -Linux users type: -```console -$ xdg-open _build/index.html -``` -macOS users type: -```console -$ open _build/index.html -``` -Windows users type: -```console -$ start _build/index.html -``` - -Others: - -enter `file:///home/user/doc-example/_build/index.html` in your browser (adapting the path to your case). - -Hopefully you can now see a website. If so, then you are able to build Sphinx pages locally. -This is useful to check how things look before pushing changes to GitHub or elsewhere. - -Note that you can change the styling by editing `conf.py` and changing the value `html_theme` -(for instance you can set it to `sphinx_rtd_theme` to have the Read the Docs look). -```` - -````{challenge} Exercise 2: Add content to your example documentation - -1. Add a entry below feature-a.rst labeled *feature-b.rst* to the `index.rst` file. -2. Create a file `feature-b.rst` in the same directory as your `feature-a.rst` file. -3. Add some content to feature-b, rebuild with `sphinx-build`, and refresh the browser to look at the results - ([Help](http://docutils.sourceforge.net/docs/ref/rst/directives.html)). - -Experiment with the following RST syntax: - -- \*Emphasized text\* and \*\*bold text\*\* -- Headings - -```rst -Level 1 -======= - -Level 2 -------- - -Level 3 -^^^^^^^ - -Level 4 -""""""" -``` - -- An image: `.. image:: image.png` -- \`A link \\`_ -- Numbered lists (can be automatic using `#`) - -```rst -1. item 1 -2. item 2 -#. item 3 -#. item 4 -``` - -- Simple tables - -```rst -====== ====== -No. Prime -====== ====== -1 No -2 Yes -3 Yes -4 No -====== ====== -``` - -- Code block using special marker `::` - -```rst -The following is a code block:: - - def hello(): - print("Hello world") -``` - -- Code block specifying syntax highlighting for other language than Python - -```rst -.. code-block:: c - - #include - int main() - { - printf("Hello, World!"); - return 0; - } -``` -- You could include the contents of an external file using `literalinclude` directive, as follows: - -```rst -.. literalinclude:: filename -``` - -- It is possible to combine `literalinclude` with code highlighting, line numbering, and even line highlighting. -- We can also use jupyter notebooks (*.ipynb) with sphinx. It requires `nbsphinx` extension to be installed. See [nbsphinx documentation](http://nbsphinx.readthedocs.io/en/latest/) for more information -```rst -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - feature-a.rst - .ipynb -``` -```` - -````{challenge} Rendering (LaTeX) math equations - -There are two different ways to display mathematical equations within Sphinx: -`pngmath` and `MathJax`. While `pngmath` displays an equation as an image, -`MathJax` is using scalable vector graphics (quality remains the same after -zooming). For this reason, we strongly encourage you to use `MathJax` for -your mathematical equations. - -To enable `MathJax` in Sphinx, you need first to add `sphinx.ext.mathjax` to -the list of extensions in `conf.py`: - -```python -extensions = ['sphinx.ext.mathjax'] -``` - -The following shows how to inline mathematics within a text: - -```rst -This is an inline equation embedded :math:`a^2 + b^2 = c^2` in text. -``` - -An equation and equation array: -```rst -.. math:: - :label: myequation - - a^2 + b^2 = c^2 - -.. math:: - :label: myarray - - \begin{eqnarray} - x^2 & : x < 0 \\ - x^3 & : x \ge 0 \\ - \end{eqnarray} -``` - -These equations can then be referenced using ``:eq:`myequation` `` and ``:eq:`myarray` ``. -```` - ---- - -### Where to find more - -- For more RST functionality, see the [Sphinx documentation](http://www.sphinx-doc.org/en/stable/rest.html) - and the [quick-reference](http://docutils.sourceforge.net/docs/user/rst/quickref.html). -- For Sphinx additions to standard RST, see [Sphinx Markup Constructs](http://www.sphinx-doc.org/en/1.7/markup/index.html). -- [https://docs.python-guide.org/writing/documentation/](https://docs.python-guide.org/writing/documentation/) - ---- - -```{keypoints} -- Sphinx and RST are relatively lightweight options for writing documentation. -``` diff --git a/content/summary.md b/content/summary.md deleted file mode 100644 index c3a005c..0000000 --- a/content/summary.md +++ /dev/null @@ -1,52 +0,0 @@ -# Summary - -```{questions} -- What recommendations can we take home? -``` - -```{discussion} -- Please write your questions in the collaborative notes document. -- Any other ideas? - - Any incremental improvements that can benefit your projects? - - What's nice but overkill for your work? - - Some of the recommendations below can be used as food for thought. -``` - ---- - -## There is not the one right way: it is always a balance - - -**Jupyter notebooks can be good documentation for scripts** - -- For simple scripts and post-processing, Jupyter notebooks can form a nice - self-documenting pipeline. - - -**README.md or README.rst?** - -- Functionality-wise both Markdown and RST are very similar. -- With RST you can generate a table of contents (TOC) automatically by adding `.. contents:: Table of Contents`. -- On GitLab you can generate a TOC in Markdown with `[[_TOC_]]`. -- Nowadays also GitHub generates a - [TOC for README.md](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes#auto-generated-table-of-contents-for-readme-files). -- If you need math equations, RST/Sphinx might be a good fit. -- Resizing images in README.rst on GitHub is currently not easy. - - -**READMEs or Read the Docs?** - -- For smaller projects READMEs can be absolutely enough. -- If the code is closed-source, you probably prefer Read the Docs (or similar). - - -**How to make sure that code changes come together with documentation changes?** - -- Make documentation part of your code review. - - -**Sphinx/RTD or GitHub pages or both?** - -- GitHub pages typically serves one version (one branch). It is often used as the project/group/personal page. -- RTD can serve several versions (several branches/tags) at the same time. -- Some projects use both. diff --git a/content/tools.md b/content/tools.md deleted file mode 100644 index 82d83e6..0000000 --- a/content/tools.md +++ /dev/null @@ -1,170 +0,0 @@ -# Popular tools and solutions - -```{questions} -- What tools are out there? -- What are their pros and cons? -``` - -```{objectives} -- Choose the right tool for the right reason. -``` - ---- - -## In-code documentation - -- Advantages - - Good for programmers - - Version controlled alongside code - - Can be used to auto-generate documentation for functions/classes -- Disadvantage - - Probably not enough for users - -We will have a closer look at this in the {ref}`in-code-documentation` episode. - ---- - -## README files - -- Advantage - - Versioned (goes with the code development) - - It is often good enough to have a `README.md` or `README.rst` along with your code/script -- If you use README files, use either - [RST](http://docutils.sourceforge.net/rst.html) or - [Markdown](https://commonmark.org/help/) - -We will have a closer look at this in the {ref}`writing-readme-files` episode. - ---- - -## reStructuredText and Markdown - -- Two of the most popular lightweight markup languages. -- reStructuredText (RST) has more features than Markdown but the choice is a matter of taste. -- Markdown convenient for smaller documents, - but for larger and more complicated documents RST may be a better option. -- There are (unfortunately) [many flavors of Markdown](https://github.com/jgm/CommonMark/wiki/Markdown-Flavors). - -``` -# This is a section in Markdown This is a section in RST - ======================== - -## This is a subsection This is a subsection - -------------------- - -Nothing special needed for Nothing special needed for -a normal paragraph. a normal paragraph. - - :: - - This is a code block This is a code block - - -**Bold** and *emphasized*. **Bold** and *emphasized*. - -A list: A list: -- this is an item - this is an item -- another item - another item - -There is more: images, There is more: images, -tables, links, ... tables, links, ... -``` - -- We will use RST in the {ref}`sphinx` episode - and Markdown in the {ref}`gh-pages` example - -Experiment with Markdown: -- [Learn Markdown in 60 seconds](http://commonmark.org/help/) -- [https://dillinger.io](http://dillinger.io) -- [https://stackedit.io](https://stackedit.io) - -To convert between MD and RST (and many other formats): -- [Pandoc](https://pandoc.org/) - ---- - -## HTML static site generators - -There are many tools that can turn RST or Markdown into beautiful HTML pages: - -- [Sphinx](http://sphinx-doc.org) **<- we will exercise this, this is how this lesson material is built** - - Generate HTML/PDF/LaTeX from RST and Markdown. - - Basically all Python projects use Sphinx but **Sphinx is not limited to Python** - - [Read the docs](http://readthedocs.org) - hosts public Sphinx documentation for free! - -- [Jekyll](https://jekyllrb.com) - - Generates HTML from Markdown. - - GitHub supports this without adding extra build steps. - -- [pkgdown](https://pkgdown.r-lib.org/) - - Popular in the R community - -- [MkDocs](https://www.mkdocs.org/) -- [GitBook](https://www.gitbook.com/) -- [Hugo](https://gohugo.io) -- [Hexo](https://hexo.io) -- [Zola](https://www.getzola.org/) **<- this is what we use for our project website and workshop websites** - -There are many more ... - -GitHub, GitLab, and Bitbucket make it possible to serve HTML pages: -- [GitHub Pages](https://pages.github.com) -- [Bitbucket Pages](https://pages.bitbucket.io/) -- [GitLab Pages](https://pages.gitlab.io) - ---- - -## Wikis - -- Popular solutions (but many others exist): - - [MediaWiki](https://www.mediawiki.org) - - [Dokuwiki](https://www.dokuwiki.org) -- Advantage - - Barrier to write and edit is low -- Disadvantages - - Typically disconnected from source code repository (**reproducibility**) - - Difficult to serve multiple versions - - Difficult to check out a specific old version - - Typically needs to be hosted and maintained - ---- - -## LaTeX/PDF - -- Advantage - - Popular and familiar in the physics and mathematics community -- Disadvantages - - PDF format is not ideal for copy-paste ability of examples - - Possible, but not trivial to automate rebuilding documentation after every Git push - ---- - -## Doxygen - -- Auto-generates API documentation -- Documented directly in the source code -- Popular in the C++ community -- Has support for C, Fortran, Python, Java, etc., - see [Doxygen Github Repo](https://github.com/doxygen/doxygen) -- Many keywords are understood by Doxygen: - [Doxygen special commands](http://www.doxygen.nl/manual/commands.html) -- Can be used to also generate higher-level ("human") documentation -- Can be deployed to GiHub/GitLab/Bitbucket Pages - ---- - -## Other tools - -- Fortran - - [Fortran Documenter (FORD)](https://github.com/Fortran-FOSS-Programmers/ford) - -- Julia - - [Franklin](https://franklinjl.org/): static site generator - - [Documenter.jl](https://juliadocs.github.io/Documenter.jl/stable/) - ---- - -```{keypoints} -- Some popular solutions make reproducibility and maintenance of multiple code versions difficult. -``` diff --git a/content/wishlist.md b/content/wishlist.md deleted file mode 100644 index 64acc6c..0000000 --- a/content/wishlist.md +++ /dev/null @@ -1,187 +0,0 @@ -# Motivation and wishlist - -## Motivation - -```{challenge} Why documenting code? - -- **Use the collaborative document**. -- Is project documentation important? Why? -- How would you describe a useful documentation? -- How can you motivate your colleagues to contribute to the documentation? -``` - -```{solution} Our motivation (but let us brainstorm first) - -- You will probably use your code in the future and may forget details. -- You may want others to use your code (almost impossible without documentation). -- You may want others to contribute to the code. -- Shield your limited time and let the documentation answer FAQs. -``` - - -## What do we expect from a suitably good documentation? - -```{discussion} Documentation comes in different forms - what *is* documentation? - - (This is adapted from: [What nobody tells you about documentation](https://www.divio.com/blog/documentation/)) - - - **Tutorials**: learning-oriented, allows the newcomer to get started - - **How-to guides**: goal-oriented, shows how to solve a specific problem - - **Explanation**: understanding-oriented, explains a concept - - **Reference**: information-oriented, describes the machinery - - These are distinct. For an excellent discussion, please see [What nobody tells you about documentation](https://www.divio.com/blog/documentation/). -``` - -**There is no one size fits all**: often for small projects a `README.md` or -`README.rst` can be enough (more about these formats later). - - -### Own examples - -```{instructor-note} -- One option is to discuss the examples below either as group discussion or in plenum. -- As an alternative to discussing these examples you can also ask students: - - Think of projects of which you like the documentation. What do you like about them? - - Think of projects for which you don’t like the documentation. What don’t you like about them? Are you missing anything? -- You can choose a mature library with lots of users for this exercise, - but try to also think of less mature projects you had to collaborate on, - or papers you had to reproduce. -``` - -We would like to show you some examples which are not ideal but we do not want -to point at others. -Instead we list some of the projects we have contributed to (possibly long time -ago), with varying quality of documentation: - -- [Dalton](https://daltonprogram.org/documentation/) (check the PDF - manuals, e.g. [Dalton 2018](https://daltonprogram.org/manuals/dalton2018manual.pdf)) -- [Cubicle](https://github.com/bast/cubicle) -- [Numgrid](https://github.com/dftlibs/numgrid) -- [MNE-Python](https://mne.tools) - -```{discussion} Pros and cons of these examples -- Dalton: - - try to copy paste input snippets from the PDF - - manual is generated manually by running LaTeX, so in practice it is often behind -- Cubicle: - - no usage examples - - one has to go into the source code to find out how to use it -- Numgrid: - - contains copy-paste-able examples - - contains recommended citation - - no tutorials with clear narration -- MNE-Python: - - easy to select version of docs - - has four "levels": tutorials, how-to guides (examples), explanation pages and API reference - - this level of documentation is overkill for small projects, but serves as a great source of ideas -``` - - -## Creating a checklist - -```{challenge} Exercise in the main room: Create a wishlist - - - **Use the collaborative document**. - - Let us create a wishlist for how we would like documentation to be. - - Below are some of our ideas but please do not look at them yet. - - We are sure you will come up with ideas we did not think about. -``` - -````{solution} Our wishlist (but let us brainstorm first) - - **Versions** - - - Your code project should be versioned (version control). - - Enable reproducibility and avoid confusion: **documentation should be versioned** as well. - - Have you ever seen: *"We will soon release a new version and are updating the documentation. - Some features may not be available in the version you have downloaded."*? - - - **Documentation should be placed and tracked close to the source code** - - - Documenting **close to the source code** (e.g. subdirectory ``doc/``) minimizes barrier to contribute. - - I should not need to log in to another machine or service and jump through hoops to contribute. - - It is often good enough to have a `README.md` or `README.rst` along with your code/script. - - - **Use a standard markup language** - - ```{instructor-note} Markup - Markup is a set of human readable instructions that is used to tell the computer how a document shall be styled and structured. By using a markup language we can for example write a `*` or `-` where we want a bullet point to appear in the rendered document. - ``` - - offers formatting flexibility, enforces a basic document structure and the rendered documents can be exported to other formats (e.g. for printing). Also, the source can be read by humans without knowledge of the language in case the rendered document is unavailable. - - We suggest to use either - [reStructuredText (RST)](http://docutils.sourceforge.net/rst.html) or - [Markdown](http://daringfireball.net/projects/markdown/) markup. - - GitHub and GitLab automatically render `README.md` or `README.rst` files. - - - **Copy-paste-able** - - - PDF alone is not enough since **copy-pasting out of a PDF document can be difficult**. - - It is OK to provide a generated PDF in addition to a copy-paste-able format. - - - **Written by humans** - - - Automatically generated documentation (e.g. API documentation) is useful as - complementary documentation but it does not replace tutorials written by - humans. - - - **Installation instructions** - - - Give **step by step instructions for the basic case**. - Additional information and caveats can be linked from there. - - List requirements and dependencies (libraries, compilers, environment). - - Include instructions for how to test for correctness after installation. - - - **Make the license explicit** - - - **Include a LICENSE file** with your source code. - - Without a license, your work is under exclusive copyright by default: - others are not allowed to re-use or modify anything. - - GitHub and GitLab allows to choose a license from common license templates. - - - **Information for contributors** - - - Make it easy for others to contribute: **document how you prefer others to contribute**. - - Users of your code may be shy to contribute code. - Your **documentation provides a platform for your first contributions**. -```` - ---- - -```{discussion} Documentation checklist - - Which items to include depends on the number of users apart from yourself. - - - Purpose - - Authors - - License - - Recommended citation - - Copy-paste-able example to get started - - Dependencies and their versions or version ranges - - Installation instructions - - Tutorials covering key functionality - - Reference documentation (e.g. API) covering all functionality - - How do you want to be asked questions (mailing list or forum or chat or issue tracker) - - Possibly a FAQ section - - Contribution guide -``` - ---- - -### Good resources - -- [A beginner’s guide to writing documentation](http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/) -- [What nobody tells you about documentation](https://www.divio.com/blog/documentation/) - -```{keypoints} -- Documentation is part of the code and should be versionable. -- Documentation (sources) should be tracked with the corresponding code in the same repository. -- Use lightweight and standard markup languages such as reStructuredText or Markdown. -``` diff --git a/content/writing-readme-files.md b/content/writing-readme-files.md deleted file mode 100644 index 65c018b..0000000 --- a/content/writing-readme-files.md +++ /dev/null @@ -1,168 +0,0 @@ -(writing-readme-files)= - -# Writing good README files - -```{questions} -- What should be included as a bare minimum in README files? -``` - -```{objectives} -- Write a README file according to good practices. -``` - ---- - -The `README` file (often `README.md` or `README.rst`) is usually the first -thing users/collaborators see when visiting your GitHub repository. Use it to -communicate important information about your project! - - -## Exercises - -```{instructor-note} -- Groups can choose to work on either exercise README-1, or on exercises README-2 + README-3. -- Exercise README-1 creates and discusses a README for an example Python project. -- Exercise README-2 can be interesting if learners already have a project/code of their own. -- Exercise README-3 (constructively) discusses READMEs of projects which you have recently used. -``` - -````{challenge} Exercise README-1: Write a README file for an example Python project -**The example project** - -Here's [the example project](https://github.com/escience-academy/coderefinery-documentation-example-project). -For this project we transformed the code snippets from the previous episode into a single script [analyse_spreadsheet.py](https://github.com/escience-academy/coderefinery-documentation-example-project/blob/main/analyse_spreadsheet.py) - -Let's take a look at [the script](https://github.com/escience-academy/coderefinery-documentation-example-project/blob/main/analyse_spreadsheet.py). -You don't need to understand the script completely, all you need to know is: -* The functions `mean_temperature` and `get_spreadsheet_columns` from previous episode are in there. -* We added a `main` function that is called when you run the script -(you could run this python script by calling `python analyse_spreadsheet.py` on the command line). -It will prompt the user for a file name, print the columns in the spreadsheet, and print the mean -temperature. - -That's all there is to this project! (You can ignore the other files in the repository, we'll get back to them in episode 4) - -**The exercise** - -1. Fork the [the example project](https://github.com/escience-academy/coderefinery-documentation-example-project) to your own github namespace -2. Add a file called `README.md` (you can use the github web interface or work locally (i.e. `git clone`, edit the file, `git add`, `git commit`, `git push`)) -3. Add some content to your README file. Think about what you want the audience to know about your project! - It does not matter whether the information is correct, it is more important that you have all the components that make up a good README file. -4. Note that the README file is nicely rendered on the github repository page. -5. Compare your README file with that of others, is all the essential information in there? -NB: The `README.md` file is written in 'Markdown' a very popular lightweight markup language, all you need to know for now is this syntax: - -``` -# A section title -## A subsection title -Normal text - -A list with items -- item1 -- item2 -``` - -(Optional): Use [https://hemingwayapp.com/](https://hemingwayapp.com/) to analyse your README file and make your writing bold and clear! -```` - -`````{solution} -A README file for this project could look like this: - -```` -### Temperature analysis in spreadsheets - -A python script for the analysis of temperatures in excel files. - - -### Why should I use this project ? - -It makes it easy to analyse excel files with temperatures in them. - - -### Setup - -You need `python>3.5` to run this script. - -The project depends on the `pandas` library, install it with pip: -`pip install pandas` - - -### How to run? - -You can run the script from the command-line using -``` -python analyse_spreadsheet.py -``` - -You can use functions directly, for example: calculate the mean temperature of some data: -```python -from analyse_spreadsheet import mean_temperature - -print(mean_temperature(data)) -``` - - -### How to cite this project? - -Please email `training@esciencecenter.nl` to get instructions on how to properly cite this project. - - -### Contributing - -You are welcome to contribute to the code via pull requests. Please have a -look at the [NLeSC -guide](https://nlesc.gitbooks.io/guide/content/software/software_overview.html) -for guidelines about software development. -```` -````` - -```{challenge} Exercise README-2: Draft or review a README for one of your recent projects -Try to draft a brief README or review a README which you have written for one -of your projects. - -You can do that either by screensharing and discussing or working individually. - -Please note observations and recommendations in the collaborative notes. -``` - -```{challenge} Exercise README-3: Review and discuss a README of a project that you have used -In this exercise we will review and discuss a README of a project which you -have used. You can also review a library which is popular in your domain of -research and discuss their README. - -You can do that either by screensharing and discussing or working individually. - -When discussing other people's projects please remember to be respectful and -constructive. The goal of this exercise is not to criticize other projects but -to learn from other projects and to collect the aspects that you enjoyed -finding in a README and to also collect aspects which you have searched for but -which are sometimes missing. - -Please note observations and recommendations in the collaborative notes. -``` - ---- - -## Table of contents in README files - -- With RST you can generate a table of contents (TOC) automatically by adding `.. contents:: Table of Contents`. -- On GitLab you can generate a TOC in Markdown with `[[_TOC_]]`. -- GitHub generates a [TOC for README.md](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/about-readmes#auto-generated-table-of-contents-for-readme-files). - ---- - -## What makes up a good README file? - -```{keypoints} -As a bare minimum a README file should include: -- A descriptive project title -- Motivation (why the project exists) -- How to setup -- Copy-pastable quick start code example -- Recommended citation -``` - -```{callout} User experience -Think about the user (**which can be a future you**) of your project, what does this user need to know to use or -contribute to the project? And how do you make your project attractive to use or contribute to? -``` From e3ac987593cc1d989b83dd2866bae63cc497672e Mon Sep 17 00:00:00 2001 From: Sunniva Indrehus Date: Fri, 4 Jun 2021 14:18:37 +0200 Subject: [PATCH 3/7] :pencil: Spell check --- content/prerequisite.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/content/prerequisite.md b/content/prerequisite.md index fc605b4..7f62278 100644 --- a/content/prerequisite.md +++ b/content/prerequisite.md @@ -1,5 +1,5 @@ # Prerequisites -This page is where you should start. You will have problems with following the steps in the documentation if some of these concepts are unfamiliar to you or you haven't been granted all the needed accesse. +This page is where you should start. You will have problems with following the steps in the documentation if some of these concepts are unfamiliar to you or you haven't been granted all the needed access. ## Technical concepts @@ -11,14 +11,14 @@ To start working with CTSM you need some basic understanding of the version cont We recommend you to take a look at CodeRefinery's [Git intro](https://coderefinery.github.io/git-intro/), [Git collaborative](https://coderefinery.github.io/git-collaborative/), and [GitHub](https://coderefinery.github.io/github-without-command-line/) lessons before you start working with CTSM. ``` -### The unix shell +### The Unix shell To start working with CTSM you need some basic understanding of how to work with the terminal. You also recommend you to set up [ssh-keys](https://documentation.sigma2.no/getting_started/create_ssh_keys.html) for login. ```{discussion} Not familiar with a terminal? We recommend taking a look at Software Carpentry's [unix shell](https://swcarpentry.github.io/shell-novice/) episode. ``` ## Needed accesses -This section is a guide to setup and use of CTSM on the Norwegian clusters +This section is a guide to the setup and use of CTSM on the Norwegian clusters run by Sigma2. ### The Sigma2-clusters @@ -37,5 +37,7 @@ and you\'re good to go. ``` ### Input data folders -All the runs of CTSM require certain input data for forcing data, grids, etc. Usually, these files are downloaded automatically from [NCAR's service](https://escomp.github.io/CESM/release-cesm2/downloading_cesm.html#downloading-input-data), but be aware of the size of the files! To avoid duplication of input files in the order of TB the users and developers of NorESM, CTSM, and other related climate models in Norway share disk space on the clusters. To get access to this folder you need to ask about the permission of the group owner. +All the runs of CTSM require certain input data for forcing data, grids, etc. Usually, these files are downloaded automatically from [NCAR's service](https://escomp.github.io/CESM/release-cesm2/downloading_cesm.html#downloading-input-data), but be aware of the size of the files! + +To avoid duplication of input files in the order of TB the users and developers of NorESM, CTSM, and other related climate models in Norway share disk space on the clusters. To get access to this folder you need to ask about the permission of the group owner. From 0d308daa1e5de4383c9d05a877df4b3404da5220 Mon Sep 17 00:00:00 2001 From: Sunniva Indrehus Date: Fri, 4 Jun 2021 14:21:30 +0200 Subject: [PATCH 4/7] :pencil: Spell check get --- content/get.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/get.md b/content/get.md index 04e701b..684dbcc 100644 --- a/content/get.md +++ b/content/get.md @@ -3,13 +3,13 @@ Dependent on what you want to do you might want to use different strategies for ```{keypoints} Path variables Throughout all this documentation we define some path variables: -- `HOME`; your home directory on the computer you are currently working on (remote or local). Typically predefined on a UNIX-system. +- `HOME`; your home directory on the computer you are currently working on (remote or local). Typically predefined on a Unix system. - `CTSM_ROOT`; the top folder or wherever you cloned CTSM ``` ## Supported machines -This tutorial assumes that you are logged into one of the clusters of Sigma2. (See [here](https://metos-uio.github.io/CTSM-Norway-Documentation/prerequisite/#needed-accesses) for ahow to get a cluster access). +This tutorial assumes that you are logged into one of the clusters of Sigma2. (See [here](https://metos-uio.github.io/CTSM-Norway-Documentation/prerequisite/#needed-accesses) for how to get cluster access). Currently (June 2021), we support machine configurations for: - saga (sigma2, Norway) @@ -24,7 +24,7 @@ A user is a person that runs CTSM without modifying the source code. To get the [~/HOME]$ git clone -b release-clm5.0 https://github.com/NordicESMhub/ctsm.git ${HOME}/ctsm_fates_emerald In this example, we are checking out the release-clm5.0 tag and create a -new local branch (recommended). The destination of the checkout is a +new local branch (recommended). The destination of the `checkout` is a directory (e.g. ctsm\_fates\_emerald) in our home directory. ### How to get a specific branch From 14e4b5f0b3d6801a0f9d63988108228c6f6d8f1a Mon Sep 17 00:00:00 2001 From: Sunniva Indrehus Date: Fri, 4 Jun 2021 14:24:09 +0200 Subject: [PATCH 5/7] :pencil: Spell check run --- content/run.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/run.md b/content/run.md index 5c6b549..2857091 100644 --- a/content/run.md +++ b/content/run.md @@ -9,7 +9,7 @@ To check which project you are affiliated with can run by typing [~/HOME]$ projects -after logging into a remote HPC-computer. This will return something that looks like this +after logging into a remote HPC-cluster. This will return something that looks like this nn2806k nn1000k @@ -23,7 +23,7 @@ To change the variable `CESM_ACCOUNT` in a script ``` ### Environmental variables -Along with the proper definition of your project you should make sure that some other environmental variables are properly defined. +Along with the proper definition of your project, you should make sure that some other environmental variables are properly defined. An example of environmental variables your might want to change are @@ -37,7 +37,7 @@ An example of environmental variables your might want to change are ## Your first CTSM case -After you have completing one of the methods in the [Get CTSM](https://metos-uio.github.io/CTSM-Norway-Documentation/get/#get-ctsm) step you need to load the correct external repositories. This you do with the command +After you have completed one of the methods in the [Get CTSM](https://metos-uio.github.io/CTSM-Norway-Documentation/get/#get-ctsm) step you need to load the correct external repositories. This you do with the command [~/CTSM_ROOT]$ ./manage_externals/checkout_externals @@ -45,7 +45,7 @@ After you have completing one of the methods in the [Get CTSM](https://metos-uio If you are updating FATES go [here](https://github.com/NordicESMhub/ctsm-dev/blob/master/Updating_FATES.md) first. ``` -### Inputdata +### The input data directory The first time, or whenever your `$WORKDIR` is cleaned, you need to link your working directory with your input data [~/CTSM_ROOT]$ cd cime/scripts From a3bf97ea5a519a1f372427a15c2a8723f226bcb8 Mon Sep 17 00:00:00 2001 From: Sunniva Indrehus Date: Fri, 4 Jun 2021 14:24:54 +0200 Subject: [PATCH 6/7] :pencil: Spell check spinup --- content/spinup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/spinup.md b/content/spinup.md index 3daa835..516cd78 100644 --- a/content/spinup.md +++ b/content/spinup.md @@ -16,7 +16,7 @@ check the *health* of your vegetation. The variable directly associated with the is `Total Leaf Area Index (TLAI)`. -If `TLAI=0` your vegetation is dead and something went really +If `TLAI=0` your vegetation is dead and something went wrong. ### How long should a spin-up be? From d0de36bf1164c37b958330a2dc41db7fcf41c64f Mon Sep 17 00:00:00 2001 From: Sunniva Indrehus Date: Fri, 4 Jun 2021 14:29:45 +0200 Subject: [PATCH 7/7] :pencil: Spell check references --- content/contribution.md | 2 +- content/license.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/contribution.md b/content/contribution.md index 4d4dfa0..7eb5fbb 100644 --- a/content/contribution.md +++ b/content/contribution.md @@ -22,4 +22,4 @@ How to automatically update the documentation locally during development: $[~/PROJECT_ROOT] sphinx-autobuild content/ _build ``` -The static webpage is hosted on Github and automatically build be pushing changes to the `main` branch. The build web-page is displayed as the stuff build on the `gh-pages` branch. This process is automatic. A guide to the principles can be found [here](https://pythonrepo.com/repo/executablebooks-sphinx-autobuild-python-documentation). +The static webpage is hosted on Github and automatically builded with GitHub-Actions by pushing changes from the `main` to the `gh-pages` branch. The built web-page is displayed as the stuff build on the `gh-pages` branch. This process is automatic. A guide to the principles can be found [here](https://pythonrepo.com/repo/executablebooks-sphinx-autobuild-python-documentation). diff --git a/content/license.md b/content/license.md index 2bfa9ed..d434dc4 100644 --- a/content/license.md +++ b/content/license.md @@ -3,9 +3,9 @@ The documentation on this webpage is made to help users of the clusters offered ## Content -The information you can find here are maintained by CTSM-Norway and is maintained as a collective effort. +The information you can find here is maintained by CTSM-Norway-Team and is maintained as a collective effort. -The people that has contributed to the content of this webpage are (listed in alfabethical order): +The people that have contributed to the content of this webpage are (listed in alphabethical order): [![](./img/profile_pictures/octocat.png)](https://github.com/ecaas) Elin Ristorp Aas