Le 18/05/2012 04:07, sam kleinman a écrit :
I think most people just follow the conventions of the python
documentation project.
Do you mean: conventions of the docutils project?
As an example, let's consider sections:
* basics and examples from docutils documentation:
http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections
* convention from Sphinx's documentation:
http://sphinx.pocoo.org/rest.html#sections
* a sample from Python library documentation:
http://docs.python.org/_sources/library/stdtypes.txt
* another sample from Python library documentation:
http://docs.python.org/_sources/library/string.txt
Where is the convention?
In fact there is at least one in Sphinx documentation, but who
follows it? Even the code sample in the Sphinx documentation
doesn't use it.
I actually don't think that this matters particularly much.
Different projects have different needs, rst doesn't "care" too much
which order you use underlines for headings as long as you do
conceptually "wrong" things, which is what you care about from a
documentation writing prospective.
I agree RST is only about markup specification, not about content.
About markup specification, I also agree RST is not a "only one way"
standard.
So I guess that the docutils project is not the best place
where to propose a style convention.
Is Sphinx project a place where a style-guide convention
could live?
My day job is as a technical writer doing stuff with sphinx and
restructured text (without Sphinx,) and the biggest barrier isn't the
style of the text files, but the conceptual background to actually be
able to write content that's relevant and appropriate, to say nothing of
actual writing skills.
+1: content matters, more than style.
I didn't mention it in the previous message, but I also shared
"documentation tips" at
https://github.com/benoitbryon/documentation-best-practices
The goal is to share recipes about documentation content.
As an example, about what is not relevant in the documentation:
http://documentation-best-practices.readthedocs.org/en/latest/external-channels/index.html
As style guide, it's currently a proposal built upon my own
experience. Feedback and contributions are welcome!
But, that's another topic...
Let's focus on RST style here and discuss about content elsewhere.
A style guide would be one thing to spend a lot of time writing, that I
don't think would have any real impact on the quality of
documentation.
Conversely, I think people might be able to create some style and
perhaps even enforce it, but I don't think that would actually force
people to write more clear sentences, to be able to structure text
inductively, to use indexing more effectively, to effectively structure
sections and documents in a hierarchy.
I agree we can't force people to use global style conventions.
But people who don't have time (or experience, or skills) to create
a brand new local style guide could be interested in shared
standards.
My primary motivation, as I proposed a style-guide, was to share
what you call "local standards": give them a chance to be reused
across various teams and projects.
But I also understand few users care of it when they write
documentation.
IMHO, a style guide would have:
* no impact on content.
* sum of small impacts on readability. As an example,
wherever your are in the RST file, you know that a title underlined
by "========" always is a H3, and a higher level than a title
underlined by "---------".
* small impact when writing: don't try to guess, just adopt the
convention. Not a big impact, but enough to focus on content
rather than on RST style.
So unlike python where PEP 8 actually makes python code more
maintainable, and less prone to errors.
I personally feel tired of switching between various RST conventions
when I switch between teams, projects or even documents: I loose
time, I make mistakes and I can't use templates. Maintenance of a
documentation written by many contributors without a style-guide
is a pain.
Maybe it *would* be a good idea
to increase the number of warnings, or include some sort of ``rstlint``
package that provided some sort of basic analysis of your RST source
file.
+1 for the sort of ``rstlint``.
Seehttps://github.com/benoitbryon/documentation-style-guide-sphinx/issues/5
andhttps://github.com/benoitbryon/documentation-style-guide-sphinx/issues/8
Contributions are welcome there too!
In fact, I guess that the kind of convention proposed in this
thread won't be adopted until some "rstlint" utility exists:
feedback really matters. I tried to explain this concept at
http://documentation-best-practices.readthedocs.org/en/latest/conventions/feedback-over-conventions.html
Which might help enforce local standards like:
- Line wrapping conventions.
- Numbers (i.e. depth) and types of outlining.
- Use of admonitions
- linking conventions.
- footnote conventions.
Could you give samples of local standards you used?
Can you open tickets about them at
https://github.com/benoitbryon/documentation-style-guide-sphinx/issues ?
I would really appreciate feedback from other "local standards".
Regards,
Benoit
With the idea that consistency trumps any particular preference....
Cheers,
sam
On Sun, May 13, 2012 at 05:22:25PM +0200, Benoît Bryon wrote:
Hi,
I am posting this message on docutils-users, sphinx-dev and doc-sig
mailing lists:
* @docutils-users, it's a proposal about some "restrictive"
reStructuredText subset;
* @sphinx-dev, it's about Sphinx usage, i.e. best practices;
* @doc-sig, I wonder if it could be a PEP for documentation of Python
packages.
I started to write down conventions for Sphinx-based documentations at
https://github.com/benoitbryon/documentation-style-guide-sphinx
I'd like to share this work, and I also need feedback.
I guess it could be compared to PEP-8, as a "style guide", but applied
to Sphinx-based documentations.
Python code can be valid even if it doesn't follow PEP-8; but Python
code should follow PEP-8 because it's the convention (and de facto
best
practice).
More explanations below.
Story
=====
As a developer, I started using Sphinx five years ago. I contributed
to
documentation of public or private projects using Sphinx. I also
worked
in several teams with different background:
* private projects with Python developers working in the same company:
* Python projects
* PHP projects (yes, Sphinx is great to document a project, even if
is not a Python project)
* public projects, with people I didn't know before.
I feel we lack some restrictive convention:
* in each team, RST usage differ. As an example, one team choose .rst
extension (sphinx-quickstart's default), whereas another choose .txt
(docutils recommendation).
* often, RST usage differ within documents of a project, depending on
the original author: one developer uses "=" for first level of
sections
whereas another uses "-" symbol.
* and many more use cases...
* as a new contributor, when I joined a project or team, I spent too
much
time discovering conventions of the project. About documentation, I
had to read current project's documentation, and often there was no
convention at all.
* when I tried to propose conventions in a team, we had discussions.
Again it's time we'd better spend on development than on discussion.
I mean it's important to discuss and to share vision, but for this
particular topic we should have used an existing convention, we
shouldn't have asked.
* when I proposed the convention from one team to another, we
discussed
it again. With other argues, and potentially a different convention
at
the end :'(
That's why I started to write down conventions in a collaborative
place,
so that every team can use it, reference it and contribute to it:
https://github.com/benoitbryon/documentation-style-guide-sphinx
Key features
============
* more restrictive than reStructuredText: as told by the Zen of
Python,
"There should be one-- and preferably only one --obvious way to do
it."
* focus on use case: Sphinx-based documentation for a project.
As an example, use Sphinx's specific directives.
* provide more than just syntax. As an example, recommend usage of
target-notes directive at the end of a document, instead of using
inline hyperlinks.
Feedback required
=================
* I wonder whether such conventions already exist or not.
* I wonder whether I should maintain a standalone convention or
contribute
to Docutils, Sphinx or even Python via a PEP... In fact, I guess I'd
rather contribute, but I am not sure...
* maybe reStructuredText documentation could include some of the
proposed conventions as recommendations, so that users naturally
use these conventions.
* maybe Sphinx documentation could recommend some points in its
reStructuredText primer.
* maybe a PEP could recommend every Python developer to follow some
style guide when they write Sphinx documents.
* ... other suggestions are welcome!
* if you are interested in the project, use it or open issues!
Regards,
--
Benoit Bryon
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email tosphinx-...@googlegroups.com.
To unsubscribe from this group, send email
tosphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group
athttp://groups.google.com/group/sphinx-dev?hl=en.
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
