README/Docs: best practice if possible about bobtemplates.plone HOT 13 CLOSED

You can remove the "if possible". We need to follow those best practices. It would be great if the docs team could review bobtemplates.plone as soon as it is ready.

Another related question: do we want to include sphinx docs in the buildout (by default, optional)?

from bobtemplates.plone.

Why optional? I would say that a small docs/source/index.rst pulling CHANGES.rst and README.rst would not harm anyone, and thus, as they already follow best practices you paved the road for them to write docs and at the same time you encourage them to do so.

from bobtemplates.plone.

I am worrysome about a default sphinx inclusion.
Pypi docs do not understand Sphinx, you cannot generate good sphinx docs that is than valid rst for pypi packages.

from bobtemplates.plone.

@do3cc but on Pypi you only show long_description from setup.py, which basically always is README.rst + CHANGES.rst, so plain rst syntax without Sphinx extensions.

from bobtemplates.plone.

My fear is that people start to add sphinx things to README.rst for the sphinx documentation. As it happened in plone.batching

from bobtemplates.plone.

This is indeed a valid point, we tried to cover this here: http://docs.plone.org/about/documentation_styleguide_addons.html#id2 and here: http://docs.plone.org/about/documentation_styleguide_addons.html#id3, maybe we should make more clear what a README is and what you should not do in a README.

from bobtemplates.plone.

svx Thanks for the pointers!

from bobtemplates.plone.

@do3cc You made a valid point. I'd be ok with not having sphinx by default. It might be overkill for most packages.

from bobtemplates.plone.

I am not convinced myself. See also my (failing) PR:
#48
It is possible to add a warning that is invisible in most renderings

from bobtemplates.plone.

I mean, I am not convinced myself that adding sphinx is bad. You can always delete it anyway

from bobtemplates.plone.

+1 I think a good readme will be enough in most cases, but we should make sure that we provide good information about that, and also point ppl to out styleguide.

Which brings me back to reason why I opened this ticket :), can we try to follow the best practices aka style guide with this repo too ?
http://docs.plone.org/about/documentation_styleguide_addons.html#id2

from bobtemplates.plone.

I am not sure, what fails at travis...

from bobtemplates.plone.

I took a look at the styleguide http://docs.plone.org/about/documentation_styleguide.html and after moving LICENSE.rst and LICENSE.GPL into top level folder I think we are good to go.

Closing, reopen if you disagree.

from bobtemplates.plone.