After finally finishing enough documentation to feel comfortable releasing v0.1, I went ahead and pushed through the release. The docs built beautifully (thanks to ReadTheDocs/Sphinx), but then I went and checked out the PDF, ePub, and HTML bundle versions of it and discovered a number of issues. Especially with the PDF version. While they all look beautiful (I couldn't possibly be more stoked on how professional they look), there are a number of issues I need to address.
General
[x] I want to change the tone of the docs. I want it to be more as though I'm writing a book or an article in a magazine than that I'm writing docs that are attached to the project I'm writing them for.
[x] Update the narrative tone throughout the documentation to be more playful, yet informative
[x] Learn more about RTD's reST syntax so that you can better mark up the text in general
[x] I want a glossary of terms
[x] I want to mark things up better so that the index comes out better
[x] I need to learn how to mark up the TOC better
From todo items in RTD source
[ ] /users_guide/facades.rst
[ ] Once you have a little more time, elaborate on the trade-off concept and provide some examples of when each interface is appropriate (facade or plain object instantiation)
[x] Go back and get rid of all some/file.csv references. I was using it incorrectly. That syntax should only be used when the filename has actual semantic value for the library
Not technically RTD, but none the less
[x] need to update README - get rid of all instructions just include links to docs and stuff
[ ] do the same thing for phpcsv.com
[ ] do the same thing anywhere else that you have docs that will become outdated on every new release (all docs should live at either csvelte.phpcsv.com or phpcsv.com/csvelte/apidocs/)
PDF Version
[ ] The main table of contents is missing--there's just a blank page where the TOC should be
[ ] The sub-sections' table of contents' are missing as well I Stand Corrected - the table of contents is there. It still could use some improvement though
[ ] There seems to be a lot of blank pages
[ ] There is a really nice index that is automatically included at the end of the PDF but it's basically barren because I need to mark up my content better so that things are properly indexed.
[ ] The cover is nice, but a bit awkward.
[ ] It contains "CSVelte Documentation" as the title and the version as the subtitle which are both fine (although I would prefer "Version 0.1 over Release 0.1 or even better, "CSVelte v0.1 Documentation" and replace subtitle with my name),
[ ] a little further down the page is my name. I would prefer it said "By Luke Visinoni" or "Authored by Luke Visinoni".
[ ] finally at the bottom it has the date, which I feel is completely out of place. if you must include the date, put it in tiny letters in the header or footer
[x] On the first page of Chapter 4 there is red text that is obviously in err. It is trying to reference :api:flavor, which in the HTML, I'm assuming, just gets ommitted. In the PDF it is quite a bit more obnoxious.
[ ] Find out if it's possible to customize the styling of the PDF at all. For instance:
[ ] Change the code syntax highlighting
[ ] Change the copy font as well as things such as headings and admonitions
[ ] Change admonition colors or other colors
[ ] Possible to force code examples onto one page? Unless they are really long.
[ ] Table formatting?
[ ] Give code examples "figure numbers" like the tables have
[ ] I want a glossary
ePub Version
[ ] I like the cover but is it possible to include the version on it? So that it says "CSVelte" on one line and then a subtitle says something like "v0.1.4" or "latest".
[ ] Possible to specify fonts?
[ ] Possible to change colors? Of the cover? Of the fonts? Of the syntax highlighting?
CSVelte-v0.1.pdf csvelte-for-php-latest.zip
After finally finishing enough documentation to feel comfortable releasing v0.1, I went ahead and pushed through the release. The docs built beautifully (thanks to ReadTheDocs/Sphinx), but then I went and checked out the PDF, ePub, and HTML bundle versions of it and discovered a number of issues. Especially with the PDF version. While they all look beautiful (I couldn't possibly be more stoked on how professional they look), there are a number of issues I need to address.
General
From todo items in RTD source
Not technically RTD, but none the less
PDF Version
flavor, which in the HTML, I'm assuming, just gets ommitted. In the PDF it is quite a bit more obnoxious.ePub Version
I have attached the PDF and HTML bundle versions of the docs. I couldn't attach the epub because GitHub wouldn't let me. But it can be downloaded here: http://readthedocs.org/projects/csvelte-for-php/downloads/epub/latest/
This issue is a continuation of issue #67 (ReadTheDocs Integration).