Repository: SINTEF/dlite (language: python)

Issue:
Guideline for how to contribute documentation



Discussion / hints:

Fix patch:
diff --git a/doc/documentation_contributors.md b/doc/documentation_contributors.md
new file mode 100644
index 000000000..bb2ec62db
--- /dev/null
+++ b/doc/documentation_contributors.md
@@ -0,0 +1,95 @@
+Guideline for contributing documentation
+========================================
+
+The DLite documentation is written in [Markdown].
+This include both the README files and documentation found in the `doc/` subdirectory.
+
+Common to both is that the text should be as easy and natural as possible to read and write both from the terminal, in an editor and rendered in a web browser.
+Hence, the following recommendations:
+
+* Write one sentence per line, in order to get an easier to read output from `git diff`.
+  This improves readability and understandability when performing reviews on GitHub.
+
+* For README files, use the underline ([setext]) style format for main and sub-headers.
+  For example:
+
+      Header level 1
+      ==============
+      ...
+
+      Header level 2
+      --------------
+      ...
+
+  For documentation, follow the style used by the original contributor.
+
+* Avoid the use of raw HTML.
+
+* Links become more readable if you place them at the end of the document using square brackets.
+  Example:
+
+```markdown
+A link to [SOFT].
+...
+
+End of document.
+
+
+[SOFT]: https://www.sintef.no/en/publications/publication/1553408/
+```
+
+* Use `.md` as file extension for all Markdown files.
+
+The README files are intended to document the overall project or the content in a subdirectory.
+These should therefore render nicely on GitHub.
+Hence, use [CommonMark] or possible [GitHub-flavored Markdown].
+For README files, keep the maximum line length at 79 characters for easy viewing in a 80 character wide terminal.
+
+The Markdown files in the `doc/` subdirectory are intended to be included in the [Sphinx]-generated [online documentation].
+We make use of the [MyST-Parser extension] to convert all markdown syntax to rich structured text (RST) prior to letting Sphinx generate the HTML (or other) documentation.
+
+
+Figures
+-------
+Please place figures in the `doc/figs/` directory.
+If you use [draw.io], it is recommended that you save the figure in svg format.
+Then it renders well in browsers and is easy to find and edit for collaborators.
+
+
+Examples
+--------
+Write your python examples in the same way as done in the [official Python documentation], by preceeding expressions with `>>> ` and the expected output on the next line below the `>>> `.
+For example
+
+    ```python
+        # Here is a python example
+        >>> x = 1 + 1
+        >>> x
+        2
+
+    ```
+
+This facilitates checking the examples by running
+
+```shell
+python -m doctest <filename>
+```
+
+on your markdown file.
+
+It is recommended to indent your code with 4 spaces.
+That makes it easy to copy the correct doctest output into your example.
+For more info, see the guide for [documentation testing].
+
+
+[Markdown]: https://en.wikipedia.org/wiki/Markdown
+[setext]: https://github.com/DavidAnson/markdownlint/blob/main/doc/md003.md
+[CommonMark]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
+[GitHub-flavored Markdown]: https://docs.github.com/en/get-started/writing-on-github
+[MyST Markdown extensions]: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
+[Sphinx]: https://www.sphinx-doc.org/
+[online documentation]: https://sintef.github.io/dlite/
+[draw.io]: https://app.diagrams.net/
+[doctest]: https://docs.python.org/3/library/doctest.html
+[official Python documentation]: https://docs.python.org/3/tutorial/introduction.html#numbers
+[documentation testing]: documentation_testing.md


Test patch:
diff --git a/doc/documentation_testing.md b/doc/documentation_testing.md
new file mode 100644
index 000000000..8f9eabba1
--- /dev/null
+++ b/doc/documentation_testing.md
@@ -0,0 +1,41 @@
+Testing Python examples in the documentation
+============================================
+
+We can use the Python [`doctest`](https://docs.python.org/3/library/doctest.html) module for testing examples in the documentation.
+Run it with
+
+    python -m doctest <filename>
+
+on your markdown file.
+
+See [documentation contributions] for how to write your examples such that they can be tested with doctest.
+
+For instance, assume that you have the following example in your documentation
+
+    ```python
+        >>> 1 + 1  # doctest: +SKIP
+        3
+
+    ```
+
+`python -m doctest documentation_testing.md` would print the following message:
+
+```shell
+**********************************************************************
+File "documentation_testing.md", line 15, in documentation_testing.md
+Failed example:
+    1 + 1
+Expected:
+    3
+Got:
+    2
+**********************************************************************
+```
+
+Now you copy the output following `Got:`, including the 4 indentation spaces, into your example.
+
+Note that the comment `#doctest: +SKIP` was added to the above example in order to not trigger a doctest failure when validating the markdown file containing this guideline.
+
+
+
+[documentation contributions]: documentation_contributions.md