PDF manual

[alexanderhiam]

It seems like many users don't find there way to the PyBBIO wiki (https://github.com/graycatlabs/PyBBIO/wiki), so there should be a generated PDF manual for each release.

I have plans to migrate the docs and tutorials to http://graycat.io, but that might not happen for a while, so the first PDF manual might have to be made from the wiki source.

[anujdeshpande]

@alexanderhiam I wrote a script to (kind of) make it easy to generate a PDF from the wiki. https://gist.github.com/anujdeshpande/0ddf9d4b7d315c6b818e Some changes to the wiki might be required : too many carriage returns at the end of the page has resulted in a number of blank pages in the final PDF. Embedded links is another. Another issue that I am getting my head around is the page numbers. But good enough to get started I guess.

[alexanderhiam]

Nice! Yeah, I'll have to clear some white space.

I'd also like to include the main page with the pinout diagram, and it would be great to generate a toc from those links. That may require using something like panadoc as a last step.

[anujdeshpande]

I tried pandoc initially. Directly converted the markdown files from the wiki git repo, but hated the formatting. Especially the code blocks. This one is a bit complicated but prettier.

[alexanderhiam]

If I remember right you can specify the stylesheet to use for markdown conversion in pandoc, so it could just use the Github stylesheet.

[alexanderhiam]

And PyPDF2 may also be able to do all that, I've never used it.

[anujdeshpande]

Yepp, it does that with grip too (easier thn pandoc), but thought it would be a better look/feel than the same old gfm. PyPDF2 mostly does merging and stuff. Also handling the headers, encryption etc.

[lucalenardi]

Hi all!

Why not using Sphinx with reStructuredText for the documentation?

• it can easily generates doc from code (supporting both C and Python);
• it is supported by GitHub;
• it lets you easily generate PDF and HTML for online documentation, even using online services such as Read The Docs. You can even add the GitHub repo to RTD to keep them synchronised.

I can create a new issue and eventually helping out porting the documentation to that format.

[alexanderhiam]

@lucalenardi I'd like to use something like Sphinx in the long run, but I don't have the time now to make that switch, so I want to do something quicker in the interim.

[alexanderhiam]

OK, it's time to bite the bullet and convert to using Sphinx - see issue #88