preparing for moving lesson to sphinx

Author: bast

.gitignore

@@ -1,3 +1,2 @@
-_drafts/
-_site/
-.sass-cache
+.jupyter_cache/
+_build/

Gemfile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = content
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Makefile

@@ -1,18 +1,13 @@
----
-layout: episode
-title: "Motivation and wishlist"
-teaching: 15
-exercises: 25
-questions:
-  - Why documenting code?
-  - What is our wishlist on a suitably good documentation?
-objectives:
-  - Arrive at a checklist for designing and deploying code 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.
----
+# Motivation and wishlist
+
+```{questions}
+- Why documenting code?
+- What is our wishlist on a suitably good documentation?
+```
+
+```{objectives}
+- Arrive at a checklist for designing and deploying code documentation.
+```
 
 ## Why documenting code?
 
@@ -171,3 +166,9 @@ or verbally), please do!
 
 - [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.
+```

_config.yml

@@ -1,16 +1,13 @@
----
-layout: episode
-title: "Popular tools and solutions"
-teaching: 10
-exercises: 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.
 keypoints:
   - Some popular solutions make reproducibility and maintenance of multiple code versions difficult.
----
+
 
 ## What tools and solutions are out there?
 

_episodes/01-wishlist.md renamed to content/01-wishlist.md

@@ -1,8 +1,5 @@
----
-layout: episode
-title: "Sphinx and reStructuredText"
-teaching: 5
-exercises: 15
+# Sphinx and reStructuredText
+
 questions:
   - How do we get started on writing Sphinx documentation in RST?
 objectives:

_episodes/03-tools.md renamed to content/03-tools.md

@@ -1,8 +1,5 @@
----
-layout: episode
-title: "Deploying Sphinx documentation to Read the Docs"
-teaching: 0
-exercises: 20
+# Deploying Sphinx documentation to Read the Docs
+
 questions:
   - How do Python projects deploy their documentation?
   - Can we use their solutions for projects which do not use Python?

_episodes/04-sphinx.md renamed to content/04-sphinx.md

@@ -1,8 +1,5 @@
----
-layout: episode
-title: "Deploying Sphinx documentation to Read the Docs"
-teaching: 0
-exercises: 20
+# Deploying Sphinx documentation to Read the Docs
+
 questions:
   - How do Python projects deploy their documentation?
   - Can we use their solutions for projects which do not use Python?

_episodes/05-rtd-gitlab.md renamed to content/05-rtd-gitlab.md

@@ -1,8 +1,5 @@
----
-layout: episode
-title: Hosting websites/homepages on GitHub Pages
-teaching: 0
-exercises: 20
+# Hosting websites/homepages on GitHub Pages
+
 questions:
   - How to serve a website/homepage using GitHub
 ---
@@ -27,7 +24,11 @@ material is hosted.
 
 ---
 
-<img src="{{ site.baseurl }}/img/gh-pages.jpg" width="50%">
+```{figure} img/gh-pages.svg
+:alt: Scheme that describes how branch names end up websites
+
+Scheme that describes how branch names end up websites.
+```
 
 ---
 

_episodes/05-rtd.md renamed to content/05-rtd.md

@@ -1,8 +1,5 @@
----
-layout: episode
-title: "Discussion after the exercises"
-teaching: 5
-exercises: 0
+# Discussion after the exercises
+
 questions:
   - What recommendations can we take home?
 ---

_episodes/06-gh-pages.md renamed to content/06-gh-pages.md

@@ -0,0 +1,103 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Code documentation lesson"
+copyright = "2021, CodeRefinery team"
+author = "CodeRefinery team"
+github_user = "coderefinery"
+github_repo_name = ""  # auto-detected from dirname if blank
+github_version = "main"
+conf_py_path = "/content/"  # with leading and trailing slash
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    # githubpages just adds a .nojekyll file
+    "sphinx.ext.githubpages",
+    "sphinx_lesson",
+    # remove once sphinx_rtd_theme updated for contrast and accessibility:
+    "sphinx_rtd_theme_ext_color_contrast",
+]
+
+# Settings for myst_nb:
+# https://myst-nb.readthedocs.io/en/latest/use/execute.html#triggering-notebook-execution
+# jupyter_execute_notebooks = "off"
+# jupyter_execute_notebooks = "auto"   # *only* execute if at least one output is missing.
+# jupyter_execute_notebooks = "force"
+jupyter_execute_notebooks = "cache"
+
+# Add any paths that contain templates here, relative to this directory.
+# templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [
+    "README*",
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "jupyter_execute",
+    "*venv*",
+]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# 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 context:
+from os.path import basename, dirname, realpath
+
+html_context = {
+    "display_github": True,
+    "github_user": github_user,
+    # Auto-detect directory name.  This can break, but
+    # useful as a default.
+    "github_repo": github_repo_name or basename(dirname(realpath(__file__))),
+    "github_version": github_version,
+    "conf_py_path": conf_py_path,
+}
+
+# Intersphinx mapping.  For example, with this you can use
+# :py:mod:`multiprocessing` to link straight to the Python docs of that module.
+# List all available references:
+#   python -msphinx.ext.intersphinx https://docs.python.org/3/objects.inv
+# extensions.append('sphinx.ext.intersphinx')
+# intersphinx_mapping = {
+#    #'python': ('https://docs.python.org/3', None),
+#    #'sphinx': ('https://www.sphinx-doc.org/', None),
+#    #'numpy': ('https://numpy.org/doc/stable/', None),
+#    #'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+#    #'pandas': ('https://pandas.pydata.org/docs/', None),
+#    #'matplotlib': ('https://matplotlib.org/', None),
+#    'seaborn': ('https://seaborn.pydata.org/', None),
+# }

_episodes/07-discussion.md renamed to content/07-discussion.md

@@ -1,8 +1,3 @@
----
-layout: default
-permalink: /guide/
----
-
 # Instructor guide
 
 * [Why we teach this lesson](#why-we-teach-this-lesson)

content/conf.py

@@ -0,0 +1,62 @@
+Code documentation lesson
+=========================
+
+In this lesson we will discuss different solutions for implementing and
+deploying code documentation.
+
+We will learn how to build documentation with the
+**documentation generator** [Sphinx](http://www.sphinx-doc.org) (and compare it
+with others) and how to
+deploy it to [Read the Docs](https://readthedocs.org), a service which hosts
+open documentation for free.
+
+This demonstration will be **independent of programming languages** and relevant
+also for your Fortran, C, C++, R, or Matlab projects.
+
+We will also learn how
+to deploy a **project website or personal homepage** to [GitHub Pages](https://pages.github.com).
+The approach that we will learn will be transferable to
+[GitLab Pages](https://about.gitlab.com/features/pages/) and
+[Bitbucket Pages](https://pages.bitbucket.io).
+
+
+.. prereq::
+
+   1. Basic understanding of Git.
+
+   2. You need to have [Sphinx](http://www.sphinx-doc.org) installed (as part of your Python environment installation).
+
+   3. You need a [GitHub](https://github.com) account (if you want to deploy the documentation via GitHub).
+
+
+.. csv-table::
+   :widths: auto
+   :delim: ;
+
+   15 min ; :doc:`01-wishlist`
+   10 min ; :doc:`03-tools`
+   20 min ; :doc:`04-sphinx`
+   20 min ; :doc:`05-rtd-gitlab`
+   20 min ; :doc:`05-rtd`
+   20 min ; :doc:`06-gh-pages`
+   5 min ; :doc:`07-discussion`
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: The lesson
+
+   01-wishlist.md
+   03-tools.md
+   04-sphinx.md
+   05-rtd-gitlab.md
+   05-rtd.md
+   06-gh-pages.md
+   07-discussion.md
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Reference
+
+   guide