Re: [openstack-dev] [docs][all] Front page template for project team documentation
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 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 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-requ...@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-requ...@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.__ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] [docs][all] Front page template for project team documentation
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 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-requ...@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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] [docs][all] Front page template for project team documentation
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-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
