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-dev@....
>> To unsubscribe from this group, send email tosphinx-dev+unsubscribe@....
>> For more options, visit this group athttp://groups.google.com/group/sphinx-dev?hl=en.
>>
|