Publish Sphinx Documentation

[camilamaia]

Publish Sphinx Documentation

The #230 implemented the auto-generated code documentation using sphinx.

We can run it locally by running

$ cd documentation
$ make html

And we can access it opening the file scanapi/documentation/build/html/index.html in a browser.

This is great, but it would be nice to have this documentation published somewhere else. One option would be to publish it inside our website scanapi.dev, repository: https://github.com/scanapi/website

[5pence]

Yes can add this in Camila :) will assign myself

[camilamaia]

Maybe a good reference of how to do this: https://github.com/marketplace/actions/sphinx-build

[camilamaia]

Hey, @5pence are you still working on this? Or should I clean the assignees up? Thank you!

[jhermann]

Just as a note, the more common subdir is docs.

And a nice feature to have is starting a sphinx-autobuild demon so any change in your editor triggers a rebuild and then a reload in your browser.

[jhermann]

If you go with RTD, the relevant docs is Incoming Webhooks and Automation — Read the Docs 5.21.0 documentation and is almost effortless usually.

docs.scanapi.dev could be added as a CNAME for the RTD domain.

[Pradhvan]

I agree with @jhermann let's go with Read The Docs with Furo Theme that urlib3 uses.

docs.scanapi.dev could be added as a CNAME for the RTD domain.

Yes, this would make sense.

[camilamaia]

💯 agreed:

• Read The Docs + Furo Theme
• docs.scanapi.dev CNAME for the RTD domain

I can set the CNAME once we have all configured for the RTD domain.

@jhermann do you want to go ahead and do the setup of the RTD?

[Pradhvan]

I can work on this too. RTD is something I have been wanting to try out. 😄

[jhermann]

@Pradhvan we can do this together tomorrow, especially regarding using the right RTD account (yours or Camila's).

Also, I wonder what's in documentation right now – API docs only? If yes, the option to switch to my normal Sphinx setup would be feasible and has some advantages regarding many conveniences already built in.
→ https://github.com/Springerle/py-generic-project/tree/master/%7B%7Bcookiecutter.repo_name%7D%7D/docs

See https://confluencer.readthedocs.io/ for an example rendering.

[camilamaia]

@Pradhvan, @jhermann
I did the RTD setup: https://scanapi.readthedocs.io/en/latest/. The webhook is also configured. It is still not rendering as expected 🤔 many docstrings are not there. Like, hide_utils for example.

@jhermann It would be nice to have the docs of all docstrings, from all methods/classes. Public and private I guess. I love your cookiecutter and how it is rendered. +1 to use your structure.

[jhermann]

OK, I'll work on a replacement -- things like hidden symbols should be handled, because I already have these things in conf.py. Will not be ready today, but likely in the course of next week.

[camilamaia]

@jhermann awesome! I will create a new issue for it and close this one, ok? Since this is pretty much done.

[camilamaia]

@jhermann here is the new issue: #469

Would mind sending a comment there saying you want to work on it so I can assign it to you?