[openstack-dev] [docs][all] Front page template for project team documentation

Jean-Philippe Evrard Jean-Philippe at evrard.me
Sat Jul 21 08:54:43 UTC 2018


Is there a lint tool that can catch incoherent markup at a global project level (vs at a page gen level)?

Any tool to catch these issues would help.

JP.

On July 19, 2018 3:55:29 PM UTC, Petr Kovar <pkovar at redhat.com> wrote:
>Hi all,
>
>A spin-off discussion in https://review.openstack.org/#/c/579177/
>resulted
>in an idea to update our RST conventions for headings level 2 and 3 so
>that
>our guidelines follow recommendations from
>http://docutils.sourceforge.net/docs/user/rst/quickstart.html#sections.
>
>The updated conventions also better reflect what most projects have
>been
>using already, regardless of what was previously in our conventions.
>
>To sum up, for headings level 2, use dashes:
>
>Heading 2
>---------
>
>For headings level 3, use tildes:
>
>Heading 3
>~~~~~~~~~
>
>For details on the change, see:
>
>https://review.openstack.org/#/c/583239/1/doc/doc-contrib-guide/source/rst-conv/titles.rst
>
>Thanks,
>pk
>
>
>On Fri, 29 Jun 2018 16:45:53 +0200
>Petr Kovar <pkovar at redhat.com> wrote:
>
>> Hi all,
>> 
>> Feedback from the Queens PTG included requests for the Documentation
>> Project to provide guidance and recommendations on how to structure
>common
>> content typically found on the front page for project team docs,
>located at
>> doc/source/index.rst in the project team repository.
>> 
>> I've created a new docs spec, proposing a template to be used by
>project
>> teams, and would like to ask the OpenStack community and,
>specifically, the
>> project teams, to take a look, submit feedback on the spec, share
>> comments, ideas, or concerns:
>> 
>>   https://review.openstack.org/#/c/579177/
>> 
>> The main goal of providing and using this template is to make it
>easier for
>> users to find, navigate, and consume project team documentation, and
>for
>> contributors to set up and maintain the project team docs.
>> 
>> The template would also serve as the basis for one of the future
>governance
>> docs tags, which is a long-term plan for the docs team.
>> 
>> Thank you,
>> pk
>> 
>>
>__________________________________________________________________________
>> OpenStack Development Mailing List (not for usage questions)
>> Unsubscribe:
>OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>
>__________________________________________________________________________
>OpenStack Development Mailing List (not for usage questions)
>Unsubscribe:
>OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
>http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20180721/78d7cf5b/attachment.html>


More information about the OpenStack-dev mailing list