Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Determine new documentation platform #192

Open
Tjzabel opened this issue Sep 26, 2019 · 13 comments
Open

Determine new documentation platform #192

Tjzabel opened this issue Sep 26, 2019 · 13 comments
Assignees
Labels
blocked Progress blocked by another task or issue documentation Improvements or additions to documentation research Research and more data is needed to make a decision

Comments

@Tjzabel
Copy link
Member

Tjzabel commented Sep 26, 2019

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.

@Tjzabel Tjzabel added documentation Improvements or additions to documentation question research Research and more data is needed to make a decision labels Sep 26, 2019
@Tjzabel Tjzabel added this to the v2.0 milestone Sep 26, 2019
@Tjzabel
Copy link
Member Author

Tjzabel commented Oct 29, 2019

@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.

@jwflory
Copy link
Member

jwflory commented Oct 30, 2019

@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.

@Tjzabel
Copy link
Member Author

Tjzabel commented Oct 30, 2019

Sure thing 👍

@jwflory
Copy link
Member

jwflory commented Nov 4, 2019

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.

@jwflory jwflory added blocked Progress blocked by another task or issue and removed question labels Nov 4, 2019
@jwflory jwflory modified the milestones: v2.0.0, v2.x.x Feb 27, 2020
@jwflory jwflory removed the blocked Progress blocked by another task or issue label Mar 14, 2020
@jwflory jwflory removed this from the v2.x.x milestone Mar 14, 2020
@jwflory
Copy link
Member

jwflory commented Mar 14, 2020

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!

@jwflory
Copy link
Member

jwflory commented Mar 21, 2020

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.

@jwflory
Copy link
Member

jwflory commented Apr 11, 2020

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:

  1. Automatically publish API docs from godoc output in our Sphinx ReadTheDocs site
  2. Publish godoc output 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.

@jwflory
Copy link
Member

jwflory commented Apr 13, 2020

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.

@jwflory jwflory added the blocked Progress blocked by another task or issue label Apr 13, 2020
@jwflory
Copy link
Member

jwflory commented May 18, 2020

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.

@jwflory
Copy link
Member

jwflory commented May 23, 2020

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.

@robbyoconnor
Copy link
Contributor

Following.

@jwflory
Copy link
Member

jwflory commented Oct 12, 2020

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.

@jwflory
Copy link
Member

jwflory commented Oct 6, 2022

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
blocked Progress blocked by another task or issue documentation Improvements or additions to documentation research Research and more data is needed to make a decision
Projects
None yet
Development

No branches or pull requests

3 participants