Demos page

[thisac]

Adds a demos page to the documentation, including a beginner's tutorial on how to use dwave-gate (taken from the examples folder). The demos are stored as Python notebooks in the docs/demos/demos folder and converted to Sphinx rst files and Jupyter notebooks using nbconvert and jupytext.

To convert a notebook into a valid Python notebook, run jupytext --to py:sphinx name_of_notebook_file.ipynb.

• Builds a page in the documentation with linked cards for the different demos.
• Stores the demos as Python notebooks for easier version control and reviews.
• Converts Python notebooks into Sphinx rst files for rendering.
• Converts Python notebooks into Jupyter notebooks for downloading.
• Runs every notebook and renders the outputs on each build.

Note: Requires Pandoc to build the correct files, along with Python packages jupytext and nbconvert (already in doc requirements), which might require some changes to the SDK build.

[codecov]

Codecov Report

Merging #35 (9f50c55) into master (bcc2140) will not change coverage.
Report is 9 commits behind head on master.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #35   +/-   ##
=======================================
  Coverage   99.87%   99.87%           
=======================================
  Files          18       18           
  Lines        1559     1559           
  Branches      263      263           
=======================================
  Hits         1557     1557           
  Misses          1        1           
  Partials        1        1           

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[JoelPasvolsky]

Just a couple of comments on installing dependencies to get the JN conversions working. It took me a while but mostly because I tried and moved on from Win and Py 3.7 environments before installing a pyenv env in my Ubuntu 16.04 VM and working with Py 3.9.
Now that I have it working locally, I'll go through the rest.

[JoelPasvolsky]

@thisac, I'm about halfway through the first demo, so I'll submit this half in case you have reservations, we can talk through before I make similar suggestions for the rest. It's too be more consistent with the writing style in the rest of our docs

[JoelPasvolsky]

I'm on an old Ubuntu with Py3.9, so this might not be supported anyway but I get

ERROR: Could not find a version that satisfies the requirement matplotlib==3.71

[thisac]

Oh, should most definitely have been 3.7.1. Thanks for the discovery.

[randomir]

A few comments on the makefile.

[randomir]

Not working for me as well (in the jupyter notebook).

[randomir]

You can use shell's built-in parameter expansion to avoid calling (external) baseline.

[randomir]

If you prefer sed, I'd extract these substitution commands in a stand-alone sed script, just to avoid the escape hell.

[randomir]

This build rule is sufficiently complex to warrant a stand-alone shell script.

Or, given how shell scripts are generally fragile, unmaintainable and unscalable, perhaps switch to something more portable and extensible, like Python? 🙂

[thisac]

Thought about it, and it's a good idea. I don't necessarily mind the simplicity of having it like this though. Perhaps leaving it like this for the time being and potentially reevaluate later.

[randomir]

Maybe you'll want to skip processing notebooks under .ipynb_checkpoints/.

[randomir]

You can also use sed's insert command to prepend text (slightly simpler expression). When combined with parameter expansion switch as suggested below:

Suggested change

	ADD_FILE_NAME_LABEL = "1s/^/.. _$$(basename $$1 .rst):\n\n/"
	ADD_FILE_NAME_LABEL = "1i .. _$${1%.rst}:\n"