RITlug
Determine new documentation platform
Our current documentation at docs.teleirc.com uses Python in order to generate readthedocs.
With our port to Go, it would make more sense to use an option that is Go friendly. This would enable us to remove our Python dependency.
@jwflory Do you feel this is something you can research this week by our next meeting? This issue is set for our next sprint, but we don't have anything besides the testing that's in slate for this week.
@Tjzabel Unfortunately I need to push for more time on this one. My senior capstone project is due in two weeks, so most of my development time is going there. This issue needs more time to research and see if the Sphinx + Go integrations are all they are cracked up to be.
I still want to pursue using Sphinx if possible. The ReadTheDocs.org team created a sphinx-autoapi extension. This extension supports Go by parsing it with the godocjson tool (also maintained by ReadTheDocs.org team). It looks like about 131 GitHub projects are already using it, and there is a fair amount of activity happening with upstream development.
It all works hypothetically, but until we start writing godoc-friendly docs, there isn't much to experiment with. I'm setting this to blocked.
Discussed in 2020-03-14 meeting.
I'm tackling this as a research task for this sprint. My next few weeks will be pretty busy, so this was the best thing I felt I could work on and accomplish. Mostly going to see how our user docs and API docs will exist, and whether they will exist together or in separate tools/platforms!
Going to bump this to the next sprint. I'm going to push priority on #265 first before going forward on this so docs can be versioned and everything will be living on one branch.
Discussed in 2020-04-11 meeting.
I haven't had much time to spend on this, but I want to do it one of two ways:
- Automatically publish API docs from
godocoutput in our Sphinx ReadTheDocs site - Publish
godocoutput on a different site, maybe GitHub Pages
Ideally we only have our docs published in one place and one place only. That's why I think Option 1 is best for TeleIRC. Option 2 is a fallback if it is not possible to embed the godoc docs into Sphinx easily.
I still want to use godocjson for this. godocjson exports the godoc-format docs into a JSON doc. What is not clear to me is whether I can use the built-in Sphinx AutoAPI extension or if I need the Sphinx JSONSchema extension. If AutoAPI works with JSON, this should be easy. If I need JSONSchema, then it all depends on how the resulting docs look like and if they are practical for our needs.
I made some headway on this. Turns out, Sphinx AutoAPI does support Go, but I couldn't get the Go bits working with Sphinx. I opened an issue upstream on readthedocs/sphinx-autoapi#196 to see if we can get to the bottom of this.
For now, I'm marking this issue as blocked because I want to see if this is possible with Sphinx AutoAPI before exploring other options. I'll wait for upstream to comment on the issue.
Upstream did not reply to my comment on the closed issue readthedocs/sphinx-autoapi#196, so I opened readthedocs/sphinx-autoapi#207 to bring it up one more time.
There was a docs issue upstream. It was fixed, but then discovered an actual bug. Upstream is responsive, it is just taking a little bit of time. This is slowly moving forward, but since it is not urgent, we can keep this on the backlog until autoapi is working right.
This briefly came up in the developer meeting yesterday. It is something on my radar, and the bug was fixed upstream. I suggested following back up on this after our testing sprint in early November.
One alternative option for me on this is that I could use the UNICEF Inventory theme for Hugo as a new approach for our documentation. It would add a limited but functional search to our documentation, give us better organization of different topics, and a better user experience than our current docs website.
The GitHub repo is here: https://github.com/unicef/inventory-hugo-theme