Create clear docs about purpose and details on how to use

[djay]

@arterrey, @ivanteoh and @jean want to have a review of the docs?

[eleddy]

This would be most excellent. I am pretty sure I want to use this, and I think there are some bugs I could fix but I can't get some basics to work. If I knew what was expected and what wasn't, I would take the time to fix things instead of filing bugs.

[datakurre]

I used this a proof-of-concept demo of generating screenshots with "acceptance tests", so this might be useful: http://elvenmagic.pandala.org/blog/html/2013/09/22/collective-listingviews.html

Source: https://github.com/datakurre/elvenmagic/blob/gh-pages/2013/09/22/collective-listingviews.rst

[djay]

Nice. That was on my todo list to use the screenshot stuff to improve the documentation. If you look back in git I originally had screenshots in my docs but they got out of date so I replaced them with doctests. I'd be more than happy if you wanted to merge that doc in

Dylan Jay Technical solution manager PretaWeb 99552830

On 24/10/2013, at 5:50 AM, Asko Soukka notifications@github.com wrote:

I used this a proof-of-concept demo of generating screenshots with "acceptance tests", so this might be useful: http://elvenmagic.pandala.org/blog/html/2013/09/22/collective-listingviews.html

Source: https://github.com/datakurre/elvenmagic/blob/gh-pages/2013/09/22/collective-listingviews.rst

— Reply to this email directly or view it on GitHubhttps://github.com/collective/collective.listingviews/issues/2#issuecomment-26934036 .

[datakurre]

I've in progress of adding all the required supportive code for screenshot generation into p.a.robotfamework and documenting it. I'll do, once I get p.a.rf 1.7.0 out.

[djay]

with the sphinx screenshot stuff, is there a relatively easy way to use it for user documentation on github and pypi? ie without having to use readthedocs? I'm guessing since pypi doesn't support images that might have to be a solution that uses both github and pypi together.

[datakurre]

Sorry for closing this by acccident.

@djay

Yes, PyPI with GitHub-hosted images would work. E.g. https://pypi.python.org/pypi/collective.behavior.localskin The downside is that you should remember to update (by running pybot for screenshot-generating test suite) and commit those images manually.

An alternative is to use Travis-CI to build docs (more than README) and deploy them into Amazon S3, but that would not embed them into PyPI.

A crazy idea would be to embed them into README using data-uris, but that might have a messy ending.

[djay]

The data-urls sounds interesting. I'm not sure what the size limit is on those when using a browser. I've only used them for pdf generation

http://stackoverflow.com/questions/695151/data-protocol-url-size-limitations

It would still require running the test suite and commiting the readme back again however so would have to be done as a manual step before push and pypi upload.

[datakurre]

@djay

We could have a new zest.releaser-plugin to execute pybot during release, fail the release process if tests for README screenshots fail, and replace image sources with data-urls only in temporary "tag dir" so that data urls are never committed to GitHub.

Once robotframework 2.8.2 is released, tests can be embedded directly into README with .. code:: robotframework-directive (and they should be hidden in PyPI with :class: hidden-option).

[djay]

On 25/10/2013, at 3:19 PM, Asko Soukka notifications@github.com wrote:

@djay

We could have a new zest.releaser-plugin to execute pybot during release, fail the release process if tests for README screenshots fail, and replace image sources with data-urls only in temporary "tag dir" so that data urls are never committed to GitHub.

except ideally we'd like to have a working readme with screenshots in github too. I think it's good enough to just have a command to run to update the docs, commit them and away you go. If the data-url thing works then we don't have to worry about where to host the images.

Once robotframework 2.8.2 is released, tests can be embedded directly into README with .. code:: robotframework-directive (and they should be hidden in PyPI with :class: hidden-option).

— Reply to this email directly or view it on GitHub.

[datakurre]

@djay Committing README with data-urls would probably need separate original for README, because 1) text README would be more difficult to edit because of long data-urls everywhere 2) it would not be trivial to replace data-urls with updated onces.

[djay]

Thats how I was thinking. README.rst.IN and then overwrite the final readme during snapshot creation. hmm.

downside of this approach is the generated readme will be unreadable as a txt file though with all these huge dataurls. but the alternative is to rely on something like github and hardcode github image urls. Both are ugly :(

[cewing]

@djay, @datakurre: I think it's worth thinking about the model @zupo has taken for plone.api on this. For that package, the README is a minimal introduction with links leading to the cannonical location for authoritative docs. That way there's no need to worry about screen shots (though in that case there are none). It also ensures that the one location where the full documentation exists is the one location where it exists. Duplication allows skew.

See https://pypi.python.org/pypi/plone.api and https://github.com/plone/plone.api for examples

[datakurre]

I don't have strong opinion on this, but I'd like to hear @djay's arguments on preferring README over Sphinx docs hosted outside pypi.

[djay]

Just that if we have a simple solution that lets me write my docs once and host it where I want without having to worry about multiple accounts is going to be more likely to be used in practice. I agree that for anything substantial like Plone.api it's worth the effort of setting up rtd. But what I have in my mind is the 100s of Plone plugins that use doctest and testbrowser now and are just hosted on pypi or Plone.org. If we had a simple solution that rendered a rst compatible with pypi and included automated screenshots and didn't require signing up to another service then I think we could have good uptake. An alternative might be to modify pypi to host images :)

[djay]

Came across this handy tip on adding screenshots to an issue in the tracker. http://solutionoptimist.com/2013/12/28/awesome-github-tricks/ @datakurre my ideal workflow would be

• add tests in the readme in github and use travis
• have travis do a step that saves images somewhere (only if they changed). Since travis is linked to github then it has to be github. So travis needs permission to be able to post something.
• have urls to images that don't change so travis doesn't also have to commit changes to the readme.
• publish to pypi such that the images still work.
• do all this without images being in the repo itself creating large pulls.

There is bound to be a clever way to do all that. Just haven't figured it out yet. Maybe something to do with using a wiki or issue and some kind of redirects in gh-pages?