remove 'Documenting Python' and its references, it's now on devguide

1 files changed, 0 insertions, 217 deletions

diff --git a/Doc/documenting/style.rst b/Doc/documenting/style.rst
deleted file mode 100644
index 2548cb0..0000000
--- a/Doc/documenting/style.rst
+++ /dev/null
@@ -1,217 +0,0 @@
-.. highlightlang:: rest
-
-Style guide
-===========
-
-The Python documentation should follow the `Apple Publications Style Guide`_
-wherever possible. This particular style guide was selected mostly because it
-seems reasonable and is easy to get online.
-
-Topics which are either not covered in Apple's style guide or treated
-differently in Python documentation will be discussed in this
-document.
-
-Use of whitespace
------------------
-
-All reST files use an indentation of 3 spaces.  The maximum line length is 80
-characters for normal text, but tables, deeply indented code samples and long
-links may extend beyond that.
-
-Make generous use of blank lines where applicable; they help grouping things
-together.
-
-A sentence-ending period may be followed by one or two spaces; while reST
-ignores the second space, it is customarily put in by some users, for example
-to aid Emacs' auto-fill mode.
-
-Footnotes
----------
-
-Footnotes are generally discouraged, though they may be used when they are the
-best way to present specific information. When a footnote reference is added at
-the end of the sentence, it should follow the sentence-ending punctuation. The
-reST markup should appear something like this::
-
-    This sentence has a footnote reference. [#]_ This is the next sentence.
-
-Footnotes should be gathered at the end of a file, or if the file is very long,
-at the end of a section. The docutils will automatically create backlinks to
-the footnote reference.
-
-Footnotes may appear in the middle of sentences where appropriate.
-
-Capitalization
---------------
-
-.. sidebar:: Sentence case
-
-   Sentence case is a set of capitalization rules used in English
-   sentences: the first word is always capitalized and other words are
-   only capitalized if there is a specific rule requiring it.
-
-Apple style guide recommends the use of title case in section titles.
-However, rules for which words should be capitalized in title case
-vary greaty between publications.
-
-In Python documentation, use of sentence case in section titles is
-preferable, but consistency within a unit is more important than
-following this rule.  If you add a section to the chapter where most
-sections are in title case you can either convert all titles to
-sentence case or use the dominant style in the new section title.
-
-Sentences that start with a word for which specific rules require
-starting it with a lower case letter should be avoided in titles and
-elsewhere.
-
-.. note::
-
-   Sections that describe a library module often have titles in the
-   form of "modulename --- Short description of the module."  In this
-   case, the description should be capitalized as a stand-alone
-   sentence.
-
-Many special names are used in the Python documentation, including the names of
-operating systems, programming languages, standards bodies, and the like. Most
-of these entities are not assigned any special markup, but the preferred
-spellings are given here to aid authors in maintaining the consistency of
-presentation in the Python documentation.
-
-Other terms and words deserve special mention as well; these conventions should
-be used to ensure consistency throughout the documentation:
-
-CPU
-   For "central processing unit." Many style guides say this should be
-   spelled out on the first use (and if you must use it, do so!). For
-   the Python documentation, this abbreviation should be avoided since
-   there's no reasonable way to predict which occurrence will be the
-   first seen by the reader. It is better to use the word "processor"
-   instead.
-
-POSIX
-   The name assigned to a particular group of standards. This is always
-   uppercase.
-
-Python
-   The name of our favorite programming language is always capitalized.
-
-reST
-   For "reStructuredText," an easy to read, plaintext markup syntax
-   used to produce Python documentation.  When spelled out, it is
-   always one word and both forms start with a lower case 'r'.
-
-Unicode
-   The name of a character coding system. This is always written
-   capitalized.
-
-Unix
-   The name of the operating system developed at AT&T Bell Labs in the early
-   1970s.
-
-Affirmative Tone
-----------------
-
-The documentation focuses on affirmatively stating what the language does and
-how to use it effectively.
-
-Except for certain security risks or segfault risks, the docs should avoid
-wording along the lines of "feature x is dangerous" or "experts only".  These
-kinds of value judgments belong in external blogs and wikis, not in the core
-documentation.
-
-Bad example (creating worry in the mind of a reader):
-
-    Warning: failing to explicitly close a file could result in lost data or
-    excessive resource consumption.  Never rely on reference counting to
-    automatically close a file.
-
-Good example (establishing confident knowledge in the effective use of the language):
-
-    A best practice for using files is use a try/finally pair to explicitly
-    close a file after it is used.  Alternatively, using a with-statement can
-    achieve the same effect.  This assures that files are flushed and file
-    descriptor resources are released in a timely manner.
-
-Economy of Expression
----------------------
-
-More documentation is not necessarily better documentation.  Err on the side
-of being succinct.
-
-It is an unfortunate fact that making documentation longer can be an impediment
-to understanding and can result in even more ways to misread or misinterpret the
-text.  Long descriptions full of corner cases and caveats can create the
-impression that a function is more complex or harder to use than it actually is.
-
-The documentation for :func:`super` is an example of where a good deal of
-information was condensed into a few short paragraphs.  Discussion of
-:func:`super` could have filled a chapter in a book, but it is often easier to
-grasp a terse description than a lengthy narrative.
-
-
-Code Examples
--------------
-
-Short code examples can be a useful adjunct to understanding.  Readers can often
-grasp a simple example more quickly than they can digest a formal description in
-prose.
-
-People learn faster with concrete, motivating examples that match the context of
-a typical use case.  For instance, the :func:`str.rpartition` method is better
-demonstrated with an example splitting the domain from a URL than it would be
-with an example of removing the last word from a line of Monty Python dialog.
-
-The ellipsis for the :attr:`sys.ps2` secondary interpreter prompt should only be
-used sparingly, where it is necessary to clearly differentiate between input
-lines and output lines.  Besides contributing visual clutter, it makes it
-difficult for readers to cut-and-paste examples so they can experiment with
-variations.
-
-Code Equivalents
-----------------
-
-Giving pure Python code equivalents (or approximate equivalents) can be a useful
-adjunct to a prose description.  A documenter should carefully weigh whether the
-code equivalent adds value.
-
-A good example is the code equivalent for :func:`all`.  The short 4-line code
-equivalent is easily digested; it re-emphasizes the early-out behavior; and it
-clarifies the handling of the corner-case where the iterable is empty.  In
-addition, it serves as a model for people wanting to implement a commonly
-requested alternative where :func:`all` would return the specific object
-evaluating to False whenever the function terminates early.
-
-A more questionable example is the code for :func:`itertools.groupby`.  Its code
-equivalent borders on being too complex to be a quick aid to understanding.
-Despite its complexity, the code equivalent was kept because it serves as a
-model to alternative implementations and because the operation of the "grouper"
-is more easily shown in code than in English prose.
-
-An example of when not to use a code equivalent is for the :func:`oct` function.
-The exact steps in converting a number to octal doesn't add value for a user
-trying to learn what the function does.
-
-Audience
---------
-
-The tone of the tutorial (and all the docs) needs to be respectful of the
-reader's intelligence.  Don't presume that the readers are stupid.  Lay out the
-relevant information, show motivating use cases, provide glossary links, and do
-your best to connect-the-dots, but don't talk down to them or waste their time.
-
-The tutorial is meant for newcomers, many of whom will be using the tutorial to
-evaluate the language as a whole.  The experience needs to be positive and not
-leave the reader with worries that something bad will happen if they make a
-misstep.  The tutorial serves as guide for intelligent and curious readers,
-saving details for the how-to guides and other sources.
-
-Be careful accepting requests for documentation changes from the rare but vocal
-category of reader who is looking for vindication for one of their programming
-errors ("I made a mistake, therefore the docs must be wrong ...").  Typically,
-the documentation wasn't consulted until after the error was made.  It is
-unfortunate, but typically no documentation edit would have saved the user from
-making false assumptions about the language ("I was surprised by ...").
-
-
-.. _Apple Publications Style Guide: http://developer.apple.com/mac/library/documentation/UserExperience/Conceptual/APStyleGuide/APSG_2009.pdf
-