Provide docs about trufont HOT 9 CLOSED

I suggest hosting the documentation with readthedocs, and using their webhooks - http://read-the-docs.readthedocs.org/en/latest/webhooks.html

Alternatively we can use travis to generate the documentation and push it to the gh-pages branch on each commit, such that https://trufont.github.io/trufont and https://trufont.github.io/defcon and so on provides the docs live on the web.

I'd like to see a 'porting from robofab to defcon' guide included in the docs at some point.

from trufont.

I'll soon opensource some modules that allow for a Github Wiki -> MkDocs -> ReadTheDocs workflow. We use it for the new docs on http://help.fontlab.com/

from trufont.

@twardoch sounds nice! However, I don't recommend using the github wiki system, I think markdown files within the main git tree is better; because the contributions to the wiki aren't counted, and there is no pull request system there. However, I know Adrien loves a clean git commit history, so maybe he doesn't want docs activity cluttering up the timeline ;p

Can your tools be extended to include the info in the code's docstrings?

from trufont.

Code docs inline the rest are tutorials on the website.

from trufont.

Actually, for a Python-based app, I'd probably recommend http://sphinx-doc.org/ after all, with sources written in reST. Markdown is good for "narrative" pieces but reST seems much better suited for code-intense docs. And it's fine for "narrative" as well, it's just a bit more complex. ReadTheDocs can consume both Sphinx- and MkDocs-generated documentation.

Sphinx is much more powerful and extensive, while MkDocs is really very simple.

For FLVI, I'll most likely be using reST+Sphinx for the Python portions and Markdown+MkDocs for the narrative docs. Both systems are Python-based and use Jinja2, so it's possible to achieve visual parity between those parts, but I'm not sure if "my" system would be a good choice for TruFont after all.

from trufont.

Since, in a way, reStructuredText is a "superset" of Markdown, it's also possible to draft or initially write the docs in Markdown, then convert to reStructuredText using Pandoc, and integrate with the code-inline Python stuff (written in reST). Then use Sphinx and host at ReadTheDocs. I myself prefer Markdown for writing, but perhaps I'll switch to reStructuredText at some point, for all authoring, or as an intermediate step.

See:

• https://gist.github.com/dupuy/1855764
• http://www.unexpected-vortices.com/doc-notes/markdown-and-rest-compared.html

from trufont.

On 26 October 2015 at 13:03, Adrien Tétar [email protected] wrote:

Code docs inline the rest are tutorials on the website

The website will be Github Jykll?

from trufont.

is

from trufont.

Closing in favor of #520.

from trufont.