http-apis.github.io Considering UI changes

The documentation is maintained in a manner that is un-structured. Building a UI that helps structure the documentation as well as using a better generator for the same can help make the experience of both the writer as well as the reader/end-user better or more streamlined.

Examples of structured documentation UIs include:

https://www.tensorflow.org/guide/
https://svelte.dev/docs

May 19 '19 17:05 de-sh

We might also consider using Pelican to generate static pages. I use it in one of my projects and I found it to be really helpful. https://www.fullstackpython.com/pelican.html

May 21 '19 03:05 chrizandr

I don't think there is any need to switch our stack. Pelican doesn't provide much as compared to Jekyll. See comparison between the two here https://www.slant.co/versus/1006/1011/~jekyll_vs_pelican

May 21 '19 04:05 xadahiya

I also think we don't need a change of static generator, but we can try out what writethedocs.org has done with rtd

Edit: links were not working

May 21 '19 04:05 de-sh

I agree with @de-sh, would be good to have a bit more structure in our docs, perhaps a search tool and for sure a side navigation along with the documentation like https://www.tensorflow.org/guide/ and https://svelte.dev/docs.

Ran into a jenkyll doc theme which might be useful: https://idratherbewriting.com/documentation-theme-jekyll/

May 22 '19 10:05 gustavodemorais

If we are still going to use Jekyll it might be a good idea to also venture out of using just and only GitHub pages. As a community, I think we are too dependent on this platform for all our requirements, I know it is a controversial opinion, but maybe we could consider using something like netlify.com for hosting our documentation. We can add a hook that deploys on each update of master.

Essentially we could drop github.io in the name of the documentation repo and still be able to use GitHub to do the source control.

Jun 15 '19 15:06 de-sh

We can also take a look at Hugo. It's written in Golang and I found it quite useful

Jun 15 '19 18:06 shravandoda

I too use Hugo 😃

But at the moment the issue is with how to build the docs to be a presentable entry-point into building with the hydraecosystem. Jekyll is good enough as @xadahiya points out, we have to create a new one, or tweak the current theme to be better suited for documentation.

Adding structure and a content framework will be most important, we have to get Amrutha's opinion on this though.

Jun 15 '19 18:06 de-sh