WIP: Generate HTML doc from Notebooks

[maxispeicher]

Issue #551:

Description of changes:
I've tried to add a first draft for generating HTML docs out of the existing notebooks. However this approach has two major downsides:

• It has some major prerequisites (nbsphinx, nbsphinx-link, IPython and pandoc)
• There are many Sphinx warnings due to duplicate labels in all of the generated HTML files from the notebooks.

Nevertheless the generation works more or less (some CSS finetuning probably required) and the Notebooks are included in the generated docs. So maybe this state can server as a starting point for discussion.

PS: @igorborgest There were some leading whitespaces copy-paste "errors" in #562. These are also fixed in this PR but I can also create a separate one for that.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[igorborgest]

I did a checkout in your branch and built it locally, I loved it!

• nbsphinx, nbsphinx-link, IPython are all python packages and will be under the developer requirements scope, so I don't worry with that.
• pandoc might be a block to build on readthedocs, I'm not sure if we have it there or if there is someway to install it.
• About copy-paste "errors", is up to you, we can wait and merge everything together if you prefer.

[igorborgest]

Also, readthedocs doesn't run our build script currently, so we will need to figure out a way to generate the link-files there.

Maybe calling the script from the Makefile??

[maxispeicher]

The link files are now created with the help of a local Sphinx extension. However pandoc in combination with readthedocs seems to be a problem:
readthedocs/readthedocs.org#4987

[igorborgest]

The link files are now created with the help of a local Sphinx extension.

Awesome!

However pandoc in combination with readthedocs seems to be a problem

I will try find out some solution 🤔

[maxispeicher]

I've also tried to use some different libraries (m2r and mdToRst) for converting Markdown to rst but they all seem to fail (e.g. with images).

[maxispeicher]

Maybe setting up the readthedocs environment with Anaconda could work: https://nbsphinx.readthedocs.io/en/0.8.1/usage.html?highlight=pandoc#Using-conda

[igorborgest]

Seems a good alternative. Could you add an equivalent file into your branch please?

I've created a specific branch to receive your PR. It will reflect here.

[maxispeicher]

The current setup should work but is still missing adjustments to navigation, formatting, etc.
It seems like the readthedocs build is not triggered but I've tested it with a quick custom setup 🎉.

[igorborgest]

It will not trigger automatically from the PR, I will need to merge it into the target branch.

[igorborgest]

Can I merge it?

You can open a second one later with the tweaks.

[maxispeicher]

Yes I think you can merge it to see if it actually works.

[igorborgest]

Awesome! It worked!

https://aws-data-wrangler.readthedocs.io/en/docs-stage/

[igorborgest]

Could you open another PR, please? We will point it to main now.

[maxispeicher]

Yes I will create another one. Do you think we should point the links in the README and docstrings to the docs page or leave them pointing to GitHub?
My intuition would be to point the README links to GitHub (as many will read it there) and point the docstring links to the documentation. WDYT?

[igorborgest]

Yes I will create another one.

Thank you! 👏

My intuition would be to point the README links to GitHub (as many will read it there) and point the docstring links to the documentation.

Makes sense to me.

p.s. Don't forget to update the tutorials link in the readthedocs header.