[docs] [issue12409] Moving "Documenting Python" to Devguide

[Sandro Tosi]

Sandro Tosi <sandro.tosi at gmail.com> added the comment:

Hi Éric,
thanks for the review.

On Fri, Jan 13, 2012 at 18:13, Éric Araujo <report at bugs.python.org> wrote:
>
> Éric Araujo <merwok at netwok.org> added the comment:
>
> About the devguide patch:
>
> a) The part about C roles and directives should probably mention version specifics (:cmacro: for 2.7, :c:macro: for 3.x) — unless you make this bug dependent on updating Sphinx to 1.0 for 2.7 and then all versions use new-style :c:.

yeah, I'd love to not write both rules/directives formats to later
revert this addition, so ok, let's make this bug depending on the
migration to sphinx 1.0 of the 2.7 version. I've sent a follow-up of
that task to python-dev some days ago, and comments (and help!) would
be welcome there too.

> b) You probably want to use ref:documenting instead of :doc:documenting (we always use ref)

ah ok, I just used the same role that was there; updated to use :ref:
- fixed that (just pushed on my repo, not updated patch yet)

> Not related to your patch, but it made me think about them so I’m just putting it out there for comments: Not sure we should keep the reST basics or just redirect to docutils and Sphinx docs.

as a matter of personal taste, I like small lists of commonly used
commands/roles/directives/whatever in the doc, with additional links
as needed, this give a quick idea (that's usually enough) on what to
do but also the possibility for further digging (if one wants it).

> Likewise, maybe it’s time to stop mentioning the old Latex-based docs.

we can do that, but maybe at a later step? so now just put the doc in
the canonical place, later let's refactor it, removing dead parts and
so on? i'm fine anyhow

>  (A nit: there are a few instances of `markup` that should be :file:`etc` or ``code``.)

I'll fix them in the mean time.

> About the cpython patch: You could just have said “rm Doc/documenting” :)

eheh, well but a tiny tiny part remains :) if we go for a redirect to
the devguide, I'm all for removing all that section from the doc; I
left it there in case someone still refers directly to documenting/ or
so (but indeed, all the sub-pages are no more reachable).

> Georg, will you be the one to set up the docs.python.org redirects?

I can provide the configuration, but I don't have access to the
machine, so some admins must be there as well.

Cheers,
Sandro

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue12409>
_______________________________________