Introducing Sphinx

[vringar]

We have long wanted HTML documentation for OpenWPM.
This is our first attempt at doing so.
This PR closes #834 and closes #820

[vringar]

@boolean5 Do you have any experience with sphinx?
I currently have none and can definitely use some assistance on this.

[vringar]

@birdsarah @englehardt Thoughts on keeping our documentation as markdown vs converting it to RST?
The main problem I encountered so far is that in the rendered HTML the relative links embedded in the Markdown are completely broken.
Also with RST we would be able to directly link to types and methods, making it harder for our documentation to reference things that no longer exist.

[codecov]

Codecov Report

Merging #863 (8497889) into master (e72ed23) will decrease coverage by 0.17%.
The diff coverage is 0.00%.

@@            Coverage Diff             @@
##           master     #863      +/-   ##
==========================================
- Coverage   50.41%   50.23%   -0.18%     
==========================================
  Files          34       34              
  Lines        3372     3372              
==========================================
- Hits         1700     1694       -6     
- Misses       1672     1678       +6     

Impacted Files	Coverage Δ
openwpm/utilities/cookie.py	0.00% <0.00%> (ø)
openwpm/utilities/multiprocess_utils.py	50.00% <0.00%> (-4.77%)	⬇️
openwpm/browser_manager.py	67.70% <0.00%> (-1.14%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update e72ed23...8497889. Read the comment docs.

[boolean5]

@boolean5 Do you have any experience with sphinx?
I currently have none and can definitely use some assistance on this.

@vringar, I have some experience in maintaining Sphinx-based documentation but not in setting it up from scratch. I'm definitely willing to help though. Let me know if you have something specific in mind.

[birdsarah]

@birdsarah @englehardt Thoughts on keeping our documentation as markdown vs converting it to RST?

I don't care either way. We just need to pick something for rendering the docs that we're willing to maintain to long term. Setting up, and therefore, changing docs frameworks is a pain. But once we're going on something it should be fine.

@boolean5 - " I have some experience in maintaining Sphinx-based documentation but not in setting it up from scratch." - that's the situation for most folks as there are far more developers than docs sites. Don't worry about it. It tends to be annoying and fiddly but it would be for any of us.

The good thing about using sphinx is that loads of folks do so there's plenty of guides out there.

[vringar]

We just need to pick something for rendering the docs that we're willing to maintain to long term.

Then I propose switching to RST. We are a python project, we want to generate docs from source and want to link to code from our documentation.
The generated docs will always be rst so we'll have to learn the syntax anyway.
(I'm mostly thinking of code snippets in the docstring and linking to related methods)

[vringar]

The only thing that is currently generating .md is the jsonschema2md which would need to be replaced by something generating rst.

[vringar]

@vringar, I have some experience in maintaining Sphinx-based documentation but not in setting it up from scratch. I'm definitely willing to help though. Let me know if you have something specific in mind.

I'm mostly looking for advice around how to structure the index.rst and how the docs folder should be structured.
Since we have two target audiences (consumers and OpenWPM developers) should we clearly split that content into two subfolders or is a flat organisation better.

[boolean5]

I'm mostly looking for advice around how to structure the index.rst and how the docs folder should be structured.
Since we have two target audiences (consumers and OpenWPM developers) should we clearly split that content into two subfolders or is a flat organisation better.

I think using a flat structure under docs is ok for now. It's enough to clearly separate user documentation from developer documentation in index.rst. The way this is done now, by using a different toctree for each section, works great.
If we later end up having many documentation files, we can rethink separating them in a user directory and a dev directory.

And another note: we should rename .readthedocs.yml to .readthedocs.yaml, as it is stated here that the .readthedocs.yml naming variant is deprecated.

[boolean5]

Are we going to need this when we will be autogenerating documentation from docstrings? Because Sphinx does not create a source directory right now when building the docs, right? Anyway, if we keep it, it would be best to group it along with docs/_build below the # Sphinx documentation comment.

[vringar]

I think it does as part of autodoc I might be wrong on this though.

[boolean5]

It seems that this depends on whether we chose to have "Separate source and build directories" when running sphinx-quickstart. If we chose not to, then we will only have a _build directory.

[boolean5]

Apart from a minor note I left this is ready to merge. Great work! 🎉