build: Add doc dependancies

[eddiebergman]

Hi Ysig,

I can't be certain that this github action will work out of the box and I will likely need to do some live debugging with respect to actions deploying to gh-pages. I can test this by deploying this actual branch doc-ci to gh-pages and seeing if it all works

Some points not tackled by this PR:

• gh-pages branch seems to have several version there although on the live published docs, there's no way to choose between them. You can however manually enter it in the url.

• There is an index.html in the gh-pages branch which points to a specific version, i.e. "0.1a8", however I do not know how to update this automatically (either by the gh-actions or even how to identify which version is latest)

  • The file looks like this

  <meta http-equiv="refresh" content="0; 0.1a8"/>

  • My proposal is that every time there is a push to master, it deploys the docs to latest
    and the index.html to be updated to reflect this, i.e.

  <meta http-equiv="refresh" content="0; latest"/>

  You can see this in the workflow file

---

Other points

• I added a new dev dependency doc which is installable with pip install -e ".[doc]"
• I had issues building the docs with Python 3.10 due to the "sphinxcontrib-bibtex==1.0" using a deprecated MutableSet from collections
• I removed/changed mentions of MultiscaleLaplacianFast from the docs as I found a changelog entry saying it was removed and replaced with MultiscaleLaplacian.
• An inventory for doc items (cross-reference other libraries) is no longer available for pynauty. I could not find a documentation page for it so I do not know how to update this link or whether such a link exists. Normally I would play around with links at published docs but it seem pynauty does not have live docs.

WARNING: failed to reach any of the inventories with the following issues:
intersphinx inventory 'https://web.cs.dal.ca/~peter/software/pynauty/html/objects.inv' not fetchable due to <class 'requests.exceptions.HTTPError'>: 404 Client Error: Not Found for url: https://web.cs.dal.ca/~peter/software/pynauty/html/objects.inv

• There are multiple warnings from sphinx when building. These are mostly duplicate citations and labels (ignorable) with one citation not found KKMMN2016
• There are some other warnings that might be worth looking at, namely 2 that look like:

/home/skantify/code/GraKeL/doc/documentation/introduction.rst:203: WARNING: Could not lex literal_block 'edges = {1: [2, 3], 2: [1], 3: [1]}\nnode_attributes = {1: [1.2, 0.5], 2: [2.8, −0.6], 3: [0.7, 1.1]}\nG = Graph(edges, node_labels=node_attributes)' as "python". Highlighting skipped.

• For some reason the doctest seems to be running any doctests present in imported scipy modules, some of which are failing (despite them seeming correct). All of GraKels doctests seem fine. This doesn't stop GraKel's documentation from building itself but it does produce errors which CI system will pick up on and likely fail (since they think the whole doc bulding failed)
      1. One option is just don't doctest for the doc release (implemented)
      2. Do the doctest but ignore errors.
      2. Lastly, fix it. However I couldn't figure it out https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

---

Written inside .github/workflows/doc.yaml

# If triggered on the master branch, then it will be pushed to the `latest` directory
# of `gh-pages`, which will be the default landing page. If this is triggered on any other
# branch, it will take the name of the branch and use it a directory name (i.e. version branch).
# This will allow us to have a landing page for each version of GraKeL.
#
# Workflow:
#   * Update `latest` by pushing to master
#   * New vesrion by manually dispatching this on a new branch
#
# Something went wrong, I need to manually inspect:
#   * git clone [email protected]/ysig/GraKeL.git
#   * git checkout gh-pages
#   * Poke around, modify as needed
#   * git add .
#   * git commit -m "Update gh-pages"
#   * git push origin gh-pages
#   * wait until GitHub deploys the changes

[codecov]

Codecov Report

Merging #101 (1682f66) into master (ea3a212) will decrease coverage by 0.05%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #101      +/-   ##
==========================================
- Coverage   67.79%   67.75%   -0.05%     
==========================================
  Files          37       37              
  Lines        7225     7225              
==========================================
- Hits         4898     4895       -3     
- Misses       2327     2330       +3     

see 1 file with indirect coverage changes

📣 Codecov offers a browser extension for seamless coverage viewing on GitHub. Try it in Chrome or Firefox today!