Open Stack

Separate from questions about whether Sphinx should handle numbered code linesproperly (it should), a style question about whether we should be numbering everything.I am finding lots of different approaches in the docs.
I would posit that, for LONG code sections, numbered lines are a pretty good idea although,in most cases, I would advocate for breaking those up into smaller sections that have discussions.
I see the following types of displays:
- Sequence of shell commands -- I advocate for no line numbers- Files, usually either configuration files or raw source code
  Here, I vacillate.  The only good reason I see for numbered lines in a small file display  is if one is going to use those numbers in the discussion of the file.  But that can be hard  to maintain unless the line numbers in the code fragment are automagically correlated with  the line numbers in the discussion.
  I have seen some code samples that have embedded comments but are still numbered.  This seems rather superfluous.  I actually prefer code samples in documentation that don't  include the code comments but, again, I know there are times when this makes sense and  one can even argue that it's a more "natural" way for geeks to get the information.
I would favor leaving most options open but it would be nice if our Markup Conventions gavesome guidelines to help people out.  I'll take the action to write up the results of this discussion.
meg

      From: Christian Berendt <christian at berendt.io>
 To: "openstack-docs at lists.openstack.org" <Openstack-docs at lists.openstack.org> 
 Sent: Monday, July 27, 2015 2:28 PM
 Subject: [OpenStack-docs] [RST] difference between the code and the code-block directive
   
Sometimes we use .. code:: and sometimes we use .. code-block::.

What is the difference? Does it makes sense to only use .. code-block:: 
and to remove the usage of .. code::?

Christian.

-- 
Christian Berendt
Cloud Solution Architect
Mail: berendt at b1-systems.de

B1 Systems GmbH
Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537

_______________________________________________
OpenStack-docs mailing list
OpenStack-docs at lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs


   
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150727/19e12784/attachment-0001.html>