mirror of
https://github.com/kennethreitz-archive/conductofcode.git
synced 2026-06-05 23:30:19 +00:00
Kenneth Reitz
288 lines
12 KiB
HTML
288 lines
12 KiB
HTML
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
|
||
<title>The Guide Style Guide — pythonguide 0.0.1 documentation</title>
|
||
|
||
<link rel="stylesheet" href="../_static/flasky.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript">
|
||
var DOCUMENTATION_OPTIONS = {
|
||
URL_ROOT: '../',
|
||
VERSION: '0.0.1',
|
||
COLLAPSE_INDEX: false,
|
||
FILE_SUFFIX: '.html',
|
||
HAS_SOURCE: true
|
||
};
|
||
</script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<link rel="top" title="pythonguide 0.0.1 documentation" href="../index.html" />
|
||
<link rel="prev" title="License" href="license.html" />
|
||
|
||
|
||
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
|
||
|
||
</head>
|
||
<body>
|
||
<div class="related">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="license.html" title="License"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><a href="../index.html">pythonguide 0.0.1 documentation</a> »</li>
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body">
|
||
|
||
<div class="section" id="the-guide-style-guide">
|
||
<span id="guide-style-guide"></span><h1>The Guide Style Guide<a class="headerlink" href="#the-guide-style-guide" title="Permalink to this headline">¶</a></h1>
|
||
<p>As with all documentation, having a consistent formating helps make the
|
||
document more understandable. In order to make The Guide easier to digest,
|
||
all contributions should fit within the rules of this style guide where
|
||
approriate.</p>
|
||
<p>The Guide is written as <a class="reference internal" href="../writing/documentation.html#restructuredtext-ref"><em>reStructuredText</em></a>.</p>
|
||
<div class="admonition note">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">Parts of The Guide may not yet match this style guide. Feel free
|
||
to update those parts to by in sync with The Guide Style Guide</p>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">On any page of the rendered HTML you can click “Show Source” to
|
||
see how authors have styled the page.</p>
|
||
</div>
|
||
<div class="section" id="relevancy">
|
||
<h2>Relevancy<a class="headerlink" href="#relevancy" title="Permalink to this headline">¶</a></h2>
|
||
<p>Stride to keep any contributions relevant to the <a class="reference internal" href="../intro/duction.html#about-ref"><em>purpose of The Guide</em></a>.</p>
|
||
<ul class="simple">
|
||
<li>Avoid including too much information on subjects that don’t directly
|
||
relate to Python development.</li>
|
||
<li>Prefer to link to other sources if the information is already out there.
|
||
Be sure to describe what and why you are linking.</li>
|
||
<li><a class="reference external" href="http://sphinx.pocoo.org/rest.html?highlight=citations#citations">Cite</a>
|
||
references where needed.</li>
|
||
<li>If a subject isn’t directly relevant to Python, but useful in conjuction
|
||
with Python (ex: Git, Github, Databases), reference by linking to useful
|
||
resouces and describe why it’s useful to Python.</li>
|
||
<li>When in doubt, ask.</li>
|
||
</ul>
|
||
</div>
|
||
<div class="section" id="headings">
|
||
<h2>Headings<a class="headerlink" href="#headings" title="Permalink to this headline">¶</a></h2>
|
||
<p>Use the following styles for headings.</p>
|
||
<p>Chapter title:</p>
|
||
<div class="highlight-python"><pre>#########
|
||
Chapter 1
|
||
#########</pre>
|
||
</div>
|
||
<p>Page title:</p>
|
||
<div class="highlight-python"><pre>===================
|
||
Time is an Illusion
|
||
===================</pre>
|
||
</div>
|
||
<p>Section headings:</p>
|
||
<div class="highlight-python"><pre>Lunchtime Doubly So
|
||
-------------------</pre>
|
||
</div>
|
||
<p>Sub section headings:</p>
|
||
<div class="highlight-python"><pre>Very Deep
|
||
~~~~~~~~~</pre>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="prose">
|
||
<h2>Prose<a class="headerlink" href="#prose" title="Permalink to this headline">¶</a></h2>
|
||
<p>Wrap text lines at 78 characters. Where necessary, lines may exceed 78
|
||
characters, especially if wrapping would make the source text more difficult
|
||
to read.</p>
|
||
</div>
|
||
<div class="section" id="code-examples">
|
||
<h2>Code Examples<a class="headerlink" href="#code-examples" title="Permalink to this headline">¶</a></h2>
|
||
<p>Wrap all code examples at 70 characters to avoid horizontal scrollbars.</p>
|
||
<p>Command line examples:</p>
|
||
<div class="highlight-python"><pre>.. code-block:: console
|
||
|
||
$ run command --help
|
||
$ ls ..</pre>
|
||
</div>
|
||
<p>Be sure to include the <tt class="docutils literal"><span class="pre">$</span></tt> prefix before each line.</p>
|
||
<p>Python interpreter examples:</p>
|
||
<div class="highlight-python"><pre>Label the example::
|
||
|
||
.. code-block:: python
|
||
|
||
>>> import this</pre>
|
||
</div>
|
||
<p>Python examples:</p>
|
||
<div class="highlight-python"><pre>Descriptive title::
|
||
|
||
.. code-block:: python
|
||
|
||
def get_answer():
|
||
return 42</pre>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="externally-linking">
|
||
<h2>Externally Linking<a class="headerlink" href="#externally-linking" title="Permalink to this headline">¶</a></h2>
|
||
<ul>
|
||
<li><p class="first">Prefer labels for well known subjects (ex: proper nouns) when linking:</p>
|
||
<div class="highlight-python"><pre>Sphinx_ is used to document Python.
|
||
|
||
.. _Sphinx: http://sphinx.pocoo.org</pre>
|
||
</div>
|
||
</li>
|
||
<li><p class="first">Prefer to use descriptive labels with inline links instead of leaving bare
|
||
links:</p>
|
||
<div class="highlight-python"><pre>Read the `Sphinx Tutorial <http://sphinx.pocoo.org/tutorial.html>`_</pre>
|
||
</div>
|
||
</li>
|
||
<li><p class="first">Avoid using labels such as “click here”, “this”, etc. preferring
|
||
decriptive labels (SEO worthy) instead.</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
<div class="section" id="linking-to-sections-in-the-guide">
|
||
<h2>Linking to Sections in The Guide<a class="headerlink" href="#linking-to-sections-in-the-guide" title="Permalink to this headline">¶</a></h2>
|
||
<p>To cross-reference other parts of this documentation, use the <a class="reference external" href="http://sphinx.pocoo.org/markup/inline.html#cross-referencing-arbitrary-locations">:ref:</a>
|
||
keyword and labels.</p>
|
||
<p>To make reference labels more clear and unique, always add a <tt class="docutils literal"><span class="pre">-ref</span></tt> suffix:</p>
|
||
<div class="highlight-python"><pre>.. _some-section-ref:
|
||
|
||
Some Section
|
||
------------</pre>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="notes-and-warnings">
|
||
<h2>Notes and Warnings<a class="headerlink" href="#notes-and-warnings" title="Permalink to this headline">¶</a></h2>
|
||
<p>Make use of the appropriate <a class="reference external" href="http://sphinx.pocoo.org/rest.html#directives">admonitions directives</a> when making notes.</p>
|
||
<p>Notes:</p>
|
||
<div class="highlight-python"><pre>.. note::
|
||
The Hitchhiker’s Guide to the Galaxy has a few things to say
|
||
on the subject of towels. A towel, it says, is about the most
|
||
massively useful thing an interstellar hitch hiker can have.</pre>
|
||
</div>
|
||
<p>Warnings:</p>
|
||
<div class="highlight-python"><pre>.. warning:: DON'T PANIC</pre>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="todos">
|
||
<h2>TODOs<a class="headerlink" href="#todos" title="Permalink to this headline">¶</a></h2>
|
||
<p>Please mark any incomplete areas of The Guide with a <a class="reference external" href="http://sphinx.pocoo.org/ext/todo.html?highlight=todo#directive-todo">todo directive</a>. To
|
||
avoid cluttering the <a class="reference internal" href="contribute.html#todo-list-ref"><em>Todo List</em></a>, use a single <tt class="docutils literal"><span class="pre">todo</span></tt> for stub
|
||
documents or large incomplete sections.</p>
|
||
<div class="highlight-python"><pre>.. todo::
|
||
Learn the Ultimate Answer to the Ultimate Question
|
||
of Life, The Universe, and Everything</pre>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar">
|
||
<div class="sphinxsidebarwrapper"><h3><a href="http://python-guide.org">Python Guide</a></h3>
|
||
<p>
|
||
This opinionated guide exists to provide both novice and expert Python developers a best-practice handbook to the installation, configuration, and usage of Python on a daily basis.
|
||
</p>
|
||
<h3><a href="../index.html">Table Of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#">The Guide Style Guide</a><ul>
|
||
<li><a class="reference internal" href="#relevancy">Relevancy</a></li>
|
||
<li><a class="reference internal" href="#headings">Headings</a></li>
|
||
<li><a class="reference internal" href="#prose">Prose</a></li>
|
||
<li><a class="reference internal" href="#code-examples">Code Examples</a></li>
|
||
<li><a class="reference internal" href="#externally-linking">Externally Linking</a></li>
|
||
<li><a class="reference internal" href="#linking-to-sections-in-the-guide">Linking to Sections in The Guide</a></li>
|
||
<li><a class="reference internal" href="#notes-and-warnings">Notes and Warnings</a></li>
|
||
<li><a class="reference internal" href="#todos">TODOs</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<h3>Related Topics</h3>
|
||
<ul>
|
||
<li><a href="../index.html">Documentation overview</a><ul>
|
||
<li>Previous: <a href="license.html" title="previous chapter">License</a></li>
|
||
</ul></li>
|
||
</ul>
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../_sources/notes/styleguide.txt"
|
||
rel="nofollow">Show Source</a></li>
|
||
</ul>
|
||
<div id="searchbox" style="display: none">
|
||
<h3>Quick search</h3>
|
||
<form class="search" action="../search.html" method="get">
|
||
<input type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
<p class="searchtip" style="font-size: 90%">
|
||
Enter search terms or a module, class or function name.
|
||
</p>
|
||
</div>
|
||
<script type="text/javascript">$('#searchbox').show(0);</script>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="footer">
|
||
© Copyright 2012. A <a href="http://kennethreitz.com/pages/open-projects.html">Kenneth Reitz</a> Project. <a href="http://creativecommons.org/licenses/by-sa/3.0/"> Creative Commons Share-Alike 3.0</a>..
|
||
</div>
|
||
<a href="https://github.com/kennethreitz/python-guide" class="github">
|
||
<img style="position: absolute; top: 0; right: 0; border: 0;" src="http://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub" />
|
||
</a>
|
||
|
||
<script type="text/javascript" src="//www.hellobar.com/hellobar.js"></script>
|
||
<script type="text/javascript">
|
||
new HelloBar(36402,48802);
|
||
</script>
|
||
|
||
<script type="text/javascript">
|
||
|
||
var _gaq2 = _gaq2 || [];
|
||
_gaq2.push(['_setAccount', 'UA-8742933-10']);
|
||
_gaq2.push(['_setDomainName', 'none']);
|
||
_gaq2.push(['_setAllowLinker', true]);
|
||
_gaq2.push(['_trackPageview']);
|
||
|
||
(function() {
|
||
var ga2 = document.createElement('script'); ga.type = 'text/javascript'; ga2.async = true;
|
||
ga2.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
||
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga2, s);
|
||
})();
|
||
|
||
</script>
|
||
|
||
<script type="text/javascript">
|
||
(function() {
|
||
var t = document.createElement('script');
|
||
t.type = 'text/javascript';
|
||
t.async = true;
|
||
t.id = 'gauges-tracker';
|
||
t.setAttribute('data-site-id',
|
||
'4ddc1cfaf5a1f50fcc000001');
|
||
t.src = '//secure.gaug.es/track.js';
|
||
var s = document.getElementsByTagName('script')[0];
|
||
s.parentNode.insertBefore(t, s);
|
||
})();
|
||
</script>
|
||
</body>
|
||
</html> |