Design process for writing documentation

[coltonlw]

Github pages only supports hosting HTML. If we want to use our Github Pages site to host docs for our whole project, we need a way to write the documentation in something like markdown, and then convert it to HTML. Sphinx generates HTML from RST. It can also be used to generate HTML from markdown. This issue is to dicsuss what want to do here

Sphinx markdown: https://github.com/ericholscher/sphinx-markdown-test Docs for "requests" package, generated from RST using Sphinx: http://docs.python-requests.org/en/master/ https://github.com/kennethreitz/requests/tree/master/docs EDIT: Found this tool for generating docs with markdown outside of sphinx: http://www.mkdocs.org/ @gsfr

[coltonlw]

@ryansanford

[ryansanford]

@coltonlw The REST API is the only interface that is treated as public, which we are now working towards 100% coverage thanks to your efforts. We can close this issue.

Now that I'm thinking about it, I should have had you remove the sphinx related material rather than relocate it, as its presence may be implying more public interfaces than intended.

[coltonlw]

@ryansanford

This issue is about how to take custom documentation that we write, e.g. tutorials or descriptions, and turn it into HTML because github pages requires that. Sphinx is not necessary for this (see mkdocs link) and the documentation doesn't and usually won't relate to module interfaces. @gsfr has said he wants to use github pages for our docs, and unless we want to write them in HTML we need a tool.

[ryansanford]

I appreciate the thinking ahead. Let's wait until we have an actionable content addition to https://scitran.github.io/core/ before we design a content management process. We'll be able to make better choices at that time.

[gsfr]

Besides the RAML, I think we also wanted to do Sphinx-based code documentation. Is that correct?

Beyond that, I'm not aware of any other needs for the moment.