Merge pull request #203 from dpshelio/w6-fixes

Improvements for week 6

Author: dpshelio

.gitignore

@@ -2,10 +2,14 @@
 output-site
 output
 _site/
+build/
+workflow/
+vendor/
 .sconsign.dblite
 html/index.html
 pdf
 *.pyc
+*.nbconvert.ipynb
 *.swp
 a.out
 html/reveal/.DS_Store

_config.yml

@@ -25,10 +25,10 @@ redcarpet:
   extensions: ["strikethrough","tables"]
 
 
-include:
-  - "ch04packaging/greetings/doc/_static"
-  - "ch04packaging/greetings/doc/_static"
-  - "ch04packaging/greetings/doc/_modules"
+include: # NOTE: This is not a path, but the directories name, wherever they are
+  - _static
+  - _modules
+
 exclude:
   - vendor/
   - Gemfile

ch02git/14Bisect.ipynb

@@ -62,7 +62,7 @@
    "source": [
     "%%bash\n",
     "rm -rf bisectdemo\n",
-    "git clone git@github.com:UCL-RITS/bisectdemo.git"
+    "git clone https://github.com/UCL-RITS/bisectdemo.git"
    ]
   },
   {

ch04packaging/04documentation.ipynb

@@ -61,15 +61,22 @@
     "together with the signature, into a web page.\n",
     "\n",
     "The most popular is [Doxygen](http://www.doxygen.nl/).\n",
-    "[Have a look at an example of some Doxygen output](\n",
-    "http://www.bempp.org/cppref/2.0/group__abstract__boundary__operators.html).\n",
     "\n",
-    "[Sphinx](http://sphinx-doc.org/) is nice for Python, and works with C++ as well.\n",
-    "Here's some [Sphinx-generated output](http://www.bempp.org/pythonref/2.0/bempp_visualization.html)\n",
-    "and the [corresponding source code](https://bitbucket.org/bemppsolutions/bempp/src/8f10af0b0b4a94bc36c6236eb9ddb2a34cde1756/python/bempp/visualization.py?at=v2.0.2&fileviewer=file-view-default).\n",
-    "[Breathe](https://breathe.readthedocs.io/en/latest/) can be used to make Sphinx and Doxygen work together.\n",
+    "Here are some other documentation tools used in different languages, have a look at the generated and source examples:\n",
     "\n",
-    "[Roxygen](https://cran.r-project.org/web/packages/roxygen2/vignettes/roxygen2.html) is good for R.\n"
+    "\n",
+    "| Language | Name                                                                                | Output example                                                                      | source                                                                                                                                           |\n",
+    "| ---      | ---                                                                                 | ---                                                                                 | ---                                                                                                                                              |\n",
+    "| Multiple | [Doxygen](http://www.doxygen.nl/)                                                   | [`Array` docs](https://eigen.tuxfamily.org/dox/classEigen_1_1Array.html)            | [`Array` docstring source](https://gitlab.com/libeigen/eigen/-/blob/55e3ae02ac1f13fbcc7a83f5e37a39fd2b142db1/Eigen/src/Core/Array.h#L26-L45)     |\n",
+    "| Python   | [Sphinx](http://sphinx-doc.org/)                                                    | [`numpy.ones` docs](https://numpy.org/doc/1.21/reference/generated/numpy.ones.html) | [`numpy.ones` docstring source](https://github.com/numpy/numpy/blob/v1.21.0/numpy/core/numeric.py#L149-L206)                                     |\n",
+    "| R        | [pkgdown](https://pkgdown.r-lib.org/) |  [`stringr`'s `str_unique`](https://stringr.tidyverse.org/reference/str_unique.html)                                                  | [`stringr`'s `str_unique` docstring source](https://github.com/tidyverse/stringr/blob/main/R/unique.R)                                                    |\n",
+    "| Julia    | [Documnenter.jl](https://juliadocs.github.io/Documenter.jl/stable/)                 | [`ones` docs](https://docs.julialang.org/en/v1/base/arrays/#Base.ones)              | [`ones` docstring source](https://github.com/JuliaLang/julia/blob/ae8452a9e0b973991c30f27beb2201db1b0ea0d3/base/array.jl#L475-L493)              |\n",
+    "| Fortan   | [FORD](https://github.com/Fortran-FOSS-Programmers/ford)                            | [`arange` docs](https://stdlib.fortran-lang.org/interface/arange.html)              | [`arange` docstring source](https://github.com/fortran-lang/stdlib/blob/d14fca8e7cc36ed5f6f84d2bf576c91c2e54eb07/src/stdlib_math.fypp#L276-L290) |\n",
+    "| Rust     | [rustdoc](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html)                   | [`Matrix` docs](https://docs.rs/nalgebra/0.18.0/nalgebra/base/struct.Matrix.html)   | [`Matrix` docstring source](https://github.com/dimforge/nalgebra/blob/8ea8ac70d5ad4bae865e6246a48455bf0b3fa3d2/src/base/matrix.rs#L59-L157)      |\n",
+    "\n",
+    "[Breathe](https://breathe.readthedocs.io/en/latest/) can be used to make Sphinx and Doxygen work together (good to keep documentation, for example, of a C++ project that includes Python bindings). [roxygen2](https://cran.r-project.org/web/packages/roxygen2/vignettes/roxygen2.html) is another good option for R packages.\n",
+    "\n",
+    "\n"
    ]
   },
   {
@@ -95,8 +102,8 @@
     "There are various conventions for how to write docstrings, but the native Sphinx one doesn't look nice when used with\n",
     "the built in `help` system.\n",
     "\n",
-    "In writing Greeter, we used the docstring conventions from NumPy.\n",
-    "So we use the [numpydoc](https://numpydoc.readthedocs.io/en/latest/) sphinx extension to \n",
+    "In writing Greeter, we used the [docstring conventions from NumPy](https://numpy.org/doc/stable/docs/howto_document.html).\n",
+    "So we use the [`numpydoc`](https://numpydoc.readthedocs.io/en/latest/) sphinx extension to\n",
     "support these (Note: you will need to install this extension for the later examples to work)."
    ]
   },
@@ -176,7 +183,7 @@
    "metadata": {},
    "source": [
     "```\n",
-    "Welcome to the Sphinx 3.3.0 quickstart utility.\n",
+    "Welcome to the Sphinx 4.2.0 quickstart utility.\n",
     "\n",
     "Please enter values for the following settings (just press Enter to\n",
     "accept a default value, if one is given in brackets).\n",
@@ -187,15 +194,41 @@
     "Either, you use a directory \"_build\" within the root path, or you separate\n",
     "\"source\" and \"build\" directories within the root path.\n",
     "> Separate source and build directories (y/n) [n]:\n",
+    "\n",
+    "The project name will occur in several places in the built documentation.\n",
+    "> Project name: Greetings\n",
+    "> Author name(s): James Hetherington\n",
+    "> Project release []: 0.1\n",
+    "\n",
+    "If the documents are to be written in a language other than English,\n",
+    "you can select a language here by its language code. Sphinx will then\n",
+    "translate text that it generates into that language.\n",
+    "\n",
+    "For a list of supported codes, see\n",
+    "https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.\n",
+    "> Project language [en]:\n",
+    "\n",
+    "Creating file ./conf.py.\n",
+    "Creating file ./index.rst.\n",
+    "Creating file ./Makefile.\n",
+    "Creating file ./make.bat.\n",
+    "\n",
+    "Finished: An initial directory structure has been created.\n",
+    "\n",
+    "You should now populate your master file /tmp/index.rst and create other documentation\n",
+    "source files. Use the Makefile to build the docs, like so:\n",
+    "   make builder\n",
+    "where \"builder\" is one of the supported builders, e.g. html, latex or linkcheck.\n",
     "```"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "and then look at and adapt the generated config, a file called\n",
-    "conf.py in the root of the project. This contains the project's Sphinx configuration, as Python variables:"
+    "and then look at and adapt the generated config - a file called\n",
+    "`conf.py` in the root of the project - with, for example, the extensions we want to use.\n",
+    "This config file contains the project's Sphinx configuration, as Python variables:"
    ]
   },
   {
@@ -247,6 +280,9 @@
     "import sys\n",
     "import os\n",
     "\n",
+    "# We need to tell Sphinx where to look for modules\n",
+    "sys.path.insert(0, os.path.abspath('.'))\n",
+    "\n",
     "extensions = [\n",
     "    'sphinx.ext.autodoc',  # Support automatic documentation\n",
     "    'sphinx.ext.coverage', # Automatically check if functions are documented\n",
@@ -257,29 +293,30 @@
     "templates_path = ['_templates']\n",
     "source_suffix = '.rst'\n",
     "master_doc = 'index'\n",
-    "project = u'Greetings'\n",
-    "copyright = u'2014, James Hetherington'\n",
+    "project = 'Greetings'\n",
+    "copyright = '2014, James Hetherington'\n",
     "version = '0.1'\n",
     "release = '0.1'\n",
-    "exclude_patterns = ['_build']\n",
+    "exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']\n",
+    "html_theme = 'alabaster'\n",
     "pygments_style = 'sphinx'\n",
     "htmlhelp_basename = 'Greetingsdoc'\n",
     "latex_elements = {\n",
     "}\n",
     "\n",
     "latex_documents = [\n",
-    "  ('index', 'Greetings.tex', u'Greetings Documentation',\n",
-    "   u'James Hetherington', 'manual'),\n",
+    "  ('index', 'Greetings.tex', 'Greetings Documentation',\n",
+    "   'James Hetherington', 'manual'),\n",
     "]\n",
     "\n",
     "man_pages = [\n",
-    "    ('index', 'greetings', u'Greetings Documentation',\n",
-    "     [u'James Hetherington'], 1)\n",
+    "    ('index', 'greetings', 'Greetings Documentation',\n",
+    "     ['James Hetherington'], 1)\n",
     "]\n",
     "\n",
     "texinfo_documents = [\n",
     "  ('index', 'Greetings', u'Greetings Documentation',\n",
-    "   u'James Hetherington', 'Greetings', 'One line description of project.',\n",
+    "   'James Hetherington', 'Greetings', 'One line description of project.',\n",
     "   'Miscellaneous'),\n",
     "]"
    ]
@@ -296,7 +333,7 @@
    "metadata": {},
    "source": [
     "\n",
-    "Sphinx uses [RestructuredText](http://docutils.sourceforge.net/rst.html) another wiki markup format similar to Markdown.\n",
+    "Sphinx uses [RestructuredText](https://docutils.sourceforge.io/rst.html) another wiki markup format similar to Markdown.\n",
     "\n",
     "You define an \"index.rst\" file to contain any preamble text you want. The rest is autogenerated by `sphinx-quickstart`\n",
     "\n",
@@ -363,7 +400,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "Running Sphinx v1.8.0\n"
+      "Running Sphinx v4.2.0\n"
      ]
     },
     {
@@ -389,7 +426,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Sphinx's output is [html](http://github-pages.ucl.ac.uk/rsd-engineeringcourse/ch04packaging/greetings/doc/index.html). We just created a simple single function's documentation, but Sphinx will create\n",
+    "Sphinx's output is [html](./greetings/doc/index.html). We just created a simple single function's documentation, but Sphinx will create\n",
     "multiple nested pages of documentation automatically for many functions.\n",
     "\n",
     "\n",
@@ -409,7 +446,7 @@
    "source": [
     "`doctest` is a module included in the standard library. It runs all the code within the docstrings and checks whether the output is what it's claimed on the documentation.\n",
     "\n",
-    "Let's add an example to our greeting function and check it with `doctest`. We are leaving the output with a small typo to see what's the type of output we get from `doctest`."
+    "Let's add an example to our greeting function and check it with `doctest`. We are leaving the output with a small typo (missing the closing quote `'`) to see what's the type of output we get from `doctest`."
    ]
   },
   {