Merge pull request #60 from s-weigand/replace-recommonmark-with-myst-…

…parser

DOC Replace recommonmark with myst-parser for markdown

.gitattributes

@@ -1,7 +1,2 @@
 *	text=lf
 *.bat	text eol=crlf
-
-docs/readme.md	symlink=file
-docs/contributing.md	symlink=file
-docs/material/cheat_sheets.md	symlink=file
-docs/material/tutorials.md	symlink=file

.github/workflows/test.yml

@@ -38,6 +38,11 @@ jobs:
         run: |
           rm -rf docs/_build
           python -m sphinx -b html docs docs/_build
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: docs
+          path: docs/_build
 
   docs-link:
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -101,57 +101,50 @@ Ready to contribute? Here's how to set up `python-tools-for-students` for local
 
 1. Fork the `python-tools-for-students` repo on GitHub.
 
-2. Clone your fork locally:
+1. Clone your fork locally:
 
    `$ git clone git@github.com:your_name_here/python-tools-for-students.git`
 
-3. Create a branch for local development:
+1. Create a branch for local development:
 
    `$ git checkout -b name-of-your-bugfix-or-feature`
 
    Now you can make your changes locally.
 
-4. Install all required libraries:
+1. Install all required libraries:
 
    `$ pip install -r requirements_dev.txt`
 
-5. Start `jupyter lab` in the folder of your local copy and write the changes you want.
+1. Start `jupyter lab` in the folder of your local copy and write the changes you want.
 
-6. Make sure all tests pass:
+1. Make sure all tests pass:
 
    `$ tox`
 
-7. Commit your changes and push your branch to GitHub:
+1. Commit your changes and push your branch to GitHub:
 
    `$ git add .`
 
    `$ git commit -m "Your detailed description of your changes."`
 
    `$ git push origin name-of-your-bugfix-or-feature`
 
-8. Submit a pull request through the GitHub website.
+1. Submit a pull request through the GitHub website.
 
-<div class="admonition note">
-
-<p class="admonition-title">Note:</p>
+```{note}
 
 You might need to [install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) if you haven't done so before.
 Especially for beginners we recommend [GitKraken](https://www.gitkraken.com/), which is a graphical user interface for `git`.
 But you should definitely learn how to work with `git` in a terminal, since you might have to work in an environment where you won't have a graphical user interface (i.e. `ssh` connection to a server/cluster where you want to do your calculation on) or something doesn't work as expected and you need to fix it.
 
-</p>
-</div>
-
-<div class="admonition note">
+```
 
-<p class="admonition-title">Note for Windows users:</p>
-<p>
+```{admonition} Note for Windows users:
 
 If you want the care free package of a 'properly' configured Posix like shell (more powerful and feature rich command line),
 just install [`cmder full`](https://cmder.net/) with [get-cmder](https://github.com/s-weigand/get-cmder).
 
-</p>
-</div>
+```
 
 ## Testing
 
@@ -209,15 +202,17 @@ you need to add them as `extra-media` entry in the `*.nblink` file.
 ### Adding markdown files
 
 Markdown files are included in the docs using
-[`recommonmark`](https://recommonmark.readthedocs.io/).
-Sadly `recommonmark` does not recognize files outside of the docs
-root folder (`docs`). So in order not to copy files and maintain two versions,
-the best solution is to use `symbolic links` inside the `docs` folder
-which point to the appropriate file.
-In order for this to work for all operating systems, you should add
-a new line to `docs/refresh_symlinks.sh`,
-and run it to create a `symbolic link` in the `docs` folder.
-After that you should add the `symlink` to `.gitattributes` as `symlink=file`.
+[`myst-parser`](https://myst-parser.readthedocs.io/en/latest/index.html).
+Sadly `sphinx` does not recognize files outside of the docs root folder (`docs`).
+So in order not to copy files and maintain two versions, the best solution is to create a new file
+inside the `docs` folder with the following code, pointing to the appropriate file.
+
+````md
+```{include} <relative_path_to_the_file_to_be_included>
+
+```
+````
+
 After that you can include it in any `*.rst` file
 [as you would normally](https://www.sphinx-doc.org/en/master/usage/quickstart.html).
 
@@ -227,15 +222,12 @@ To build the documentation, open a terminal, navigate to the `docs` folder and
 run `make html` (Posix like) / `make.bat html` (Windows).
 This will create the documentation inside the folder `docs/_build/html`.
 
-<div class="admonition note">
-
-<p class="admonition-title">Note:</p>
-<p>
+```{note}
 For the docs to be build it is mandatory that you use a conda installation of python or at least have conda installed.
 This is due to the fact that the notebook inclusion in the docs utilizes the tool [pandoc](https://pandoc.org/).
 Even so `pandoc` is present in many package manager repository indices, this is mostly a too old version,
 which is why we recommend to use the [version provided by conda](https://anaconda.org/conda-forge/pandoc).
-</p>
+```
 
 ```bash
 $ conda install -c conda-forge pandoc
@@ -244,22 +236,15 @@ $ conda install -c conda-forge pandoc
 This also requires that the terminal you execute the make command with knows about the conda binary path/s
 (see [Using Anaconda only if needed](https://python-tools-for-students.readthedocs.io/en/latest/getting_started.html#using-anaconda-only-if-needed)).
 
-</div>
-
-<div class="admonition note">
-
-<p class="admonition-title">Note for Windows users:</p>
-<p>
+```{admonition} Note for Windows users:
 
 If you are on Windows and want to use [git bash for Windows](https://gitforwindows.org/),
 you might not have the `make` command installed.
 To install `make` into git bash you can follow
 [this guide](https://gist.github.com/evanwill/0207876c3243bbb6863e65ec5dc3f058#make) or use
 `install_make_git_bash_standalone.bat` from [get-cmder](https://github.com/s-weigand/get-cmder).
 
-</p>
-
-</div>
+```
 
 ## Style guide
 

docs/conf.py

@@ -32,7 +32,7 @@
     "nbsphinx",
     "nbsphinx_link",
     "sphinx_copybutton",
-    "recommonmark",
+    "myst_parser",
     "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.extlinks",
@@ -127,7 +127,7 @@
 }
 
 linkcheck_ignore = [
-    r'https://github\.com/students-teach-students/python-tools-for-students/actions',
+    r"https://github\.com/students-teach-students/python-tools-for-students/actions",
 ]
 
 # -- Options for HTML output -------------------------------------------
@@ -146,7 +146,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+# html_static_path = ["_static"]
 
 
 # -- Options for HTMLHelp output ---------------------------------------
@@ -171,7 +171,7 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = "python_tools_for_studentsdoc"
 
-linkcheck_ignore = [r'https:\/\/gist\.github\.com\/.*#']
+linkcheck_ignore = [r"https:\/\/gist\.github\.com\/.*#"]
 # -- Options for LaTeX output ------------------------------------------
 
 # See https://www.sphinx-doc.org/en/master/latex.html

docs/contributing.md

@@ -0,0 +1,3 @@
+```{include} ../CONTRIBUTING.md
+
+```

docs/material/cheat_sheets.md

@@ -0,0 +1,3 @@
+```{include} ../../material/cheat_sheets.md
+
+```

docs/material/tutorials.md

@@ -0,0 +1,3 @@
+```{include} ../../material/tutorials.md
+
+```

docs/readme.md

@@ -0,0 +1,3 @@
+```{include} ../README.md
+
+```

requirements_dev.txt

@@ -5,13 +5,13 @@
 tox>=3.4.0
 pytest>=5.1.3
 nbval>=0.9.2
-flake8-nb>=0.1.0
+flake8-nb>=0.2.1
 
 # documentation
 Sphinx>=2.2.0
-sphinx-copybutton>=0.2.5
-recommonmark>=0.6.0
-sphinx-rtd-theme>=0.4.3
+sphinx-copybutton>=0.3.0
+myst-parser>=0.12.0
+sphinx-rtd-theme>=0.5.0
 nbsphinx>=0.4.2
 nbsphinx-link>=1.3.0
 ipykernel>=5.1.2