Hi! We have the devguide now, and it should be the place where to look for references and docs about contributing to Python, that means also for the documentation.

In the official Python doc we have a section "Documenting Python" (http://docs.python.org/py3k/documenting/index.html) and I think it should be merged into the devguide - what's your opinion on that?

-1

> Hi! We have the devguide now, and it should be the place where to look
> for references and docs about contributing to Python, that means also
> for the documentation.

For information specific to the Python documentation itself, but not
relevant to users documenting their own projects, yes.

> In the official Python doc we have a section "Documenting Python"
> (http://docs.python.org/py3k/documenting/index.html) and I think it
> should be merged into the devguide - what's your opinion on that?

The scope of this document is much larger than Python's documentation,
but extends to all projects written in Python that use Sphinx as their
documentation tool.  With that, it makes sense to keep it as part of
the documentation for users of Python.

Hi Fred, thanks for your input! Let's see what others think, but I think that at the very least, the "Building the documentation" section (that seams very specific to python) should be moved into the devguide.

I agree with Fred.

I don’t understand Fred’s replies.

> The scope of this document is much larger than Python's documentation,
> but extends to all projects written in Python that use Sphinx as their
> documentation tool.
Really?  docs.python.org/documenting is much smaller that sphinx.pocoo.org, and only seems to cover documenting Python, not any Python project.

> With that, it makes sense to keep it as part of the documentation for
> users of Python.
I don’t follow.  You’re saying that since the document also covers other projects than Python, it makes sense to include it in the Python docs?

IMO, the criterion for the devguide is to have version-independent documents in one place instead of needlessly including them with CPython and having to sync across versions.  For the Documenting Python docs, if they contain version-specific instructions, or if they contain instructions needed in a CPython tarball, then they’re in the right place, otherwise they could move to the devguide.

From IRC:

<fdrake> After last being pressed on this, I got to thinking about it more.  Back in the day, that's all the doc there was about the tool-chain.  With Sphinx standing as a successful independent project, the tool documentation need no longer be part of any of the python.org docs; what's left probably can be moved.
<fdrake> (Yes, I'm withdrawing my objection.)

So, I am in favor of moving the Python-specific parts of Doc/documenting (if any) to the devguide and just link to the upstream Sphinx docs (which are a subset of our Doc/documenting) for the markup and suchlike.

+1

+1

@Fred: thanks about it :)

@Éric: I just want to have clear in mind what you mean; my original proposal was to move completely, the whole section "Documenting python" to devguide since it contains building instructions and how's the markup works for python. Is your proposal different and so, as I can read, to just move the building part to devguide and the rest of it be left in python documentation with links to sphinx upstream documentation?

But one aspect I think it needs to be done as a prerequisite to this migration is: standardizing the sphinx/tools versions used to build the doc.

devguide is version-agnostic, so we can talk about (without convoluted sentences) only about one way to build the doc.

This was raised several times, even recently, on python-dev so I'm going to resurrect that thread so we can discuss there the pros/cons and then see from the outcome how we can move forward.

My comment was ambiguous, let me rephrase it: I am in favor of moving cpython/Doc/documenting to the devguide.  Then, in the devguide, I would like to remove all the doc that’s just duplicating the upstream Sphinx docs, keeping only links and Python-specific parts.

> But one aspect I think it needs to be done as a prerequisite to this migration is:
> standardizing the sphinx/tools versions used to build the doc.
If this gets rejected, we can move the Documenting tree to the devguide anyway, we’ll just have to add a few paragraphs for 2.7 differences.

+1, and as Eric says, we can do it without changing versions of Sphinx used.

Hi,
i'm at last back with some work to show; I've integrated all the "Documenting python" doc into devguide, and the commits are in this sandbox: http://hg.python.org/sandbox/morph-devguide/shortlog/a92d431ef749 (`documenting` branch).

I took the files from default branch and merged all of them in a single page. It might be a bit log, but it has the advantage (at least for me) that there you can find all the info you need for documenting python, a ctrl+f works and you don't need to follow tons of links to find what you're looking for.

then I've removed all the info from default branch (here: http://hg.python.org/sandbox/morph/shortlog/e9a4276b19d4 in default-documenting branch) which left only documenting/index.rst as mainly a reference to the devguide.

I don't know what would be the best way to handle this transition on the python doc side, maybe converting that to a simple Doc/documenting.rst as it's now index.rst? but what text to left?

Comments are very welcome!

Could you provide a single patch or publish your version somewhere to help reviews?

For the CPython docs, I think just removing the whole of Doc/documenting would be okay, or if we expect that people will go to that URI we may leave a placeholder page with only links.  Georg?

Sure, sorry I didn't make it before; here attached the 2 patches, one against devguide, the other to default cpython repo.

We'll probably have to redirect all /documenting in Apache anyway.

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:.

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

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.  Likewise, maybe it’s time to stop mentioning the old Latex-based docs.  (A nit: there are a few instances of `markup` that should be :file:`etc` or ``code``.)

About the cpython patch: You could just have said “rm Doc/documenting” :)  Georg, will you be the one to set up the docs.python.org redirects?

Hi Éric,
thanks for the review.

On Fri, Jan 13, 2012 at 18:13, Éric Araujo <report@bugs.python.org> wrote:
>
> Éric Araujo <merwok@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

I just replied to your python-dev email.  I think you can update 2.7 to use Sphinx 1.0 as soon as you’re down to a handful of warnings.

When the migration is done, you can add the documenting doc to the devguide and send a message to pydev to tell people to not commit changes to Doc/documenting in CPython clones anymore.

In the same email you can ask who to ask for setting up redirects (BTW, will redirecting paths to fragments work?  e.g. docs.py.o/documenting/style to devguide/documenting#style-and-blah).  When the redirects are up you’ll be able to rm Doc/documenting.

Then we’ll open other reports to talk about the unrelated I mentioned and to see how to stop downloading Sphinx from svn once per clone :)

On Sat, Jan 14, 2012 at 04:36, Éric Araujo <report@bugs.python.org> wrote:
>
> Éric Araujo <merwok@netwok.org> added the comment:
>
> I just replied to your python-dev email.  I think you can update 2.7 to use Sphinx 1.0 as soon as you’re down to a handful of warnings.

thanks! I've just updated 2.7 to sphinx 1.0 - yay

> When the migration is done, you can add the documenting doc to the devguide and send a message to pydev to tell people to not commit changes to Doc/documenting in CPython clones anymore.
>
> In the same email you can ask who to ask for setting up redirects (BTW, will redirecting paths to fragments work?  e.g. docs.py.o/documenting/style to devguide/documenting#style-and-blah).  When the redirects are up you’ll be able to rm Doc/documenting.

I just did that with:
http://mail.python.org/pipermail/python-dev/2012-January/115520.html

> Then we’ll open other reports to talk about the unrelated I mentioned and to see how to stop downloading Sphinx from svn once per clone :)

Ah yes, sure!

Cheers,
Sandro

"Documenting Python" has been:

- moved to devguide; http://hg.python.org/devguide/rev/5d4a90e568ed
- removed from 2.7, 3.2 and default;
    http://hg.python.org/cpython/rev/8975f7d0fbf7
    http://hg.python.org/cpython/rev/70c46599fb0e
    http://hg.python.org/cpython/rev/900c01e643a7

Thanks everyone!

Glad my action plan worked :)

There are now obsolete entries in the Doc/tools/sphinxext/susp-ignored.csv file: All lines starting with “documenting” can be removed.

New changeset 7167c04780ed by Sandro Tosi in branch '2.7':
Issue: #12409: remove obsolete susp-entries
http://hg.python.org/cpython/rev/7167c04780ed

New changeset 153e32333aaa by Sandro Tosi in branch '3.2':
Issue: #12409: remove obsolete susp-entries
http://hg.python.org/cpython/rev/153e32333aaa

New changeset a6bf08666da2 by Sandro Tosi in branch 'default':
Issue: #12409: merge with 3.2
http://hg.python.org/cpython/rev/a6bf08666da2

Éric, thanks for spotting it: removed.