Better documentation

[iliana]

For an API, datagrepper's documentation is fairly unreadable. No table of contents, no good navigation between parts of the page, way too much whitespace on the page (lots and lots of wasted space).

I would like to create something similar to this page: https://stripe.com/docs/api

[jwflory]

I'm interested in helping with this. Even improving the layout and navigation could be helpful. But I'm also not sure how to work with the project documentation. How are the datagrepper docs set up now? Is it beneficial to migrate to a Fedora Docs setup?

cc: @ralphbean @bexelbie

[jeremycline]

Typically we use Sphinx for docs, but datagrepper is doing a weird thing: it has some RST files inside the Python package and pre-renders them to HTML:

datagrepper/datagrepper/app.py

Line 139 in 5a47f52

def preload_docs(endpoint):

then serves them with a flask endpoint:

datagrepper/datagrepper/app.py

Line 196 in 5a47f52

@app.route('/reference')

This is weird because there's no dynamic content so it makes little sense to have Flask handle serving the files. Much better to build them with Sphinx and let the web server handle them. I recommend pulling the docs directory out of the Python package and into the root of the repo as "docs/" or similar. Then you can let RTD serve them or do what Bodhi does and serve them with Apache: https://bodhi.stg.fedoraproject.org/docs/

[jwflory]

@jeremycline Is there a central Fedora RTD account? If not, could you or someone else add me to the fedora-infra GitHub organization so I can play with it in my account for this repo?

[jeremycline]

There is not (as far as I know). I went ahead and set up a project on RTD, though: https://readthedocs.org/projects/datagrepper/. What's your RTD username? I can add you to the project as an admin and you should have everything you need to get the docs going.

I don't have permissions to add you to the fedora-infra GitHub org so if you want that, I think you'll need to file an infra ticket.

[jwflory]

@jeremycline My RTD username is jwf. Let me know if that works!

I'll go ahead and file a ticket on Pagure for that.

[jeremycline]

@jflory7 Done, you should be able to do whatever you want for the RTD project. If you have questions or need any help, just let me know.

[jwflory]

Ahhh, the lovely feeling of coming across an issue that describes a problem you are facing, only to find that you volunteered (unsuccessfully) to help solve the problem 5+ years ago. I suppose this is how it goes sometimes… 😀

Anyways, I am thinking it might be best to close this issue as not planned. I think it is better to open more specific issues that cover specific user stories as it relates to documentation, like I did with #562. While some of the issues detailed in this nearly 10-year old issue are solved, some are not. I'm not sure keeping it open provides much benefit to Datagrepper at this point (even though I would agree that the docs still need a lot of love).

@abompard Any thoughts here on this one?