Plans for Sphinx 1.2
244 views
Skip to first unread message
Georg Brandl
Dec 10, 2012, 1:23:30 AM12/10/12
to sphin...@googlegroups.com
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hi all,
when I asked who would be interested in maintenance and development
of Sphinx a few weeks ago, there was a great response. So far, the
following people have gotten push access:
Ervin Hegedï¿œs
Jon Waltman
Kevin Hunter
La Min Ko
Nikolaj van Omme
Robert Lehmann
Roland Meister
Takayuki Shimizukawa
There has already been a lot of activity, and I am very thankful for
that. And for those who have not been active yet, there is absolutely
no obligation for anything, but please don't hesitate to write to this
list if we can do something for you.
I would like to get a version 1.2 out at some time "between the years",
i.e. between 24th of December and 6th of January. For that, I would like
to know *your* plans: what features or bugs do you feel have to go in
or be fixed before the release?
Thanks,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
iEYEARECAAYFAlDFf+IACgkQN9GcIYhpnLBfOQCeKMUDQyh9XBzrdqXy8bktdZk9
MOQAn3dlmEBbAX1XfEi7AtvPxVpvmsfC
=4vFC
-----END PGP SIGNATURE-----
Hash: SHA1
Hi all,
when I asked who would be interested in maintenance and development
of Sphinx a few weeks ago, there was a great response. So far, the
following people have gotten push access:
Ervin Hegedï¿œs
Jon Waltman
Kevin Hunter
La Min Ko
Nikolaj van Omme
Robert Lehmann
Roland Meister
Takayuki Shimizukawa
There has already been a lot of activity, and I am very thankful for
that. And for those who have not been active yet, there is absolutely
no obligation for anything, but please don't hesitate to write to this
list if we can do something for you.
I would like to get a version 1.2 out at some time "between the years",
i.e. between 24th of December and 6th of January. For that, I would like
to know *your* plans: what features or bugs do you feel have to go in
or be fixed before the release?
Thanks,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
iEYEARECAAYFAlDFf+IACgkQN9GcIYhpnLBfOQCeKMUDQyh9XBzrdqXy8bktdZk9
MOQAn3dlmEBbAX1XfEi7AtvPxVpvmsfC
=4vFC
-----END PGP SIGNATURE-----
Jonathan Waltman
Dec 11, 2012, 4:46:13 AM12/11/12
to sphin...@googlegroups.com
On Mon, Dec 10, 2012 at 12:23 AM, Georg Brandl <ge...@python.org> wrote:
...
There was also some talk on Docutils 0.10 coming out soon, so we
might get a little time to work against a stable release and
catch any issues.
> For that, I would like to know *your* plans: what features or bugs
> do you feel have to go in or be fixed before the release?
These aren't by any means show stoppers but might be nice
things to add.
1) Make autodoc easier to debug and customize. Provide an easier
way to access and manipulate live objects. Here are some ideas:
Directly exec/eval code in the directives themselves:
.. autofunction:: bar
:exec: from other.mod import foo as bar
Provide a new directive for executing blocks of code in a custom
environment used to look up objects to document (similar to
how the testsetup directive works in the doctest extension).
.. autodocsetup:: ns
from mod import *
foo.__doc__ = process_doc(foo)
.. autofunction:: foo
:namespace: ns
2) Provide a way to get the intermediate reST generated by
autodoc directives. Useful for debugging and actually seeing
what the expanded form looks like.
This could be just a configuration variable like
`autodoc_debug_expanded` which causes each form to be printed
whenever the directive is ran.
More debugging flags in general would be nice to help people track
down problems or understand what's going on with their docs.
3) sphinx-apidoc should work more like sphinx-autogen, in that it
should analyze / import python source files and generate
configurable output instead of just using `automodule`.
Cheers,
Jonathan Waltman
...
> I would like to get a version 1.2 out at some time "between the years",
> i.e. between 24th of December and 6th of January.
Sounds goods.
> i.e. between 24th of December and 6th of January.
There was also some talk on Docutils 0.10 coming out soon, so we
might get a little time to work against a stable release and
catch any issues.
> For that, I would like to know *your* plans: what features or bugs
> do you feel have to go in or be fixed before the release?
things to add.
1) Make autodoc easier to debug and customize. Provide an easier
way to access and manipulate live objects. Here are some ideas:
Directly exec/eval code in the directives themselves:
.. autofunction:: bar
:exec: from other.mod import foo as bar
Provide a new directive for executing blocks of code in a custom
environment used to look up objects to document (similar to
how the testsetup directive works in the doctest extension).
.. autodocsetup:: ns
from mod import *
foo.__doc__ = process_doc(foo)
.. autofunction:: foo
:namespace: ns
2) Provide a way to get the intermediate reST generated by
autodoc directives. Useful for debugging and actually seeing
what the expanded form looks like.
This could be just a configuration variable like
`autodoc_debug_expanded` which causes each form to be printed
whenever the directive is ran.
More debugging flags in general would be nice to help people track
down problems or understand what's going on with their docs.
3) sphinx-apidoc should work more like sphinx-autogen, in that it
should analyze / import python source files and generate
configurable output instead of just using `automodule`.
Cheers,
Jonathan Waltman
Takayuki Shimizukawa
Dec 11, 2012, 9:54:34 AM12/11/12
to sphin...@googlegroups.com
Hi there,
2012/12/10 Georg Brandl <ge...@python.org>:
:bugs:
* i18n issues #940 #960 #975 #976 #1036
:feature:
* Human-readable objects.inv #1052
* Include anonymous label target in 'objects.inv' for intersphinx #1050
i18n translation feature was introduced at Sphinx-1.1 release that is
very important for multi-language documentation (e.g. sphinx-doc.org,
docs.python.org ) but current Sphinx & docutils have several problems
(above issues).
The intersphinx makes it easy to integrate/divide the document.
But current Sphinx does not contain enough label-target information,
and it is difficult to know the name of the label then its
availability is limited.
# Because I'll hold sphinx-users.jp general meeting tomorrow then I'm
going to discuss this topic.
Best regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa
2012/12/10 Georg Brandl <ge...@python.org>:
> I would like to get a version 1.2 out at some time "between the years",
> i.e. between 24th of December and 6th of January. For that, I would like
> to know *your* plans: what features or bugs do you feel have to go in
> or be fixed before the release?
I think there are several issues to reduce the availability of the Sphinx.
> i.e. between 24th of December and 6th of January. For that, I would like
> to know *your* plans: what features or bugs do you feel have to go in
> or be fixed before the release?
:bugs:
* i18n issues #940 #960 #975 #976 #1036
:feature:
* Human-readable objects.inv #1052
* Include anonymous label target in 'objects.inv' for intersphinx #1050
i18n translation feature was introduced at Sphinx-1.1 release that is
very important for multi-language documentation (e.g. sphinx-doc.org,
docs.python.org ) but current Sphinx & docutils have several problems
(above issues).
The intersphinx makes it easy to integrate/divide the document.
But current Sphinx does not contain enough label-target information,
and it is difficult to know the name of the label then its
availability is limited.
# Because I'll hold sphinx-users.jp general meeting tomorrow then I'm
going to discuss this topic.
Best regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa
Sam Kleinman
Dec 11, 2012, 10:40:18 AM12/11/12
to sphin...@googlegroups.com
I'll root for my issues:
- https://bitbucket.org/birkenfeld/sphinx/issue/880/cross-referencing-program-objects
- https://bitbucket.org/birkenfeld/sphinx/issue/1054/gettext-output-includes-restructured-text
The first is an old one, that remains frustrating. There's no good way
to index/reference objects for a (whole) binary, apart from indexing the
command line options. Basically I want to be able to have a document
that includes: ::
:program:`sphinx-build`
And have it link to the "man page" in my documentation for the
sphinx-build executable.
The second is just a current annoyance with the PO output, that I've
been meaning to bring up for a while...
Cheers,
sam
On Monday, December 10 2012, 01:23:30, Georg Brandl wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> Hi all,
>
> when I asked who would be interested in maintenance and development
> of Sphinx a few weeks ago, there was a great response. So far, the
> following people have gotten push access:
>
> Jon Waltman
> Kevin Hunter
> La Min Ko
> Nikolaj van Omme
> Robert Lehmann
> Roland Meister
> Takayuki Shimizukawa
>
> There has already been a lot of activity, and I am very thankful for
> that. And for those who have not been active yet, there is absolutely
> no obligation for anything, but please don't hesitate to write to this
> list if we can do something for you.
>
> I would like to get a version 1.2 out at some time "between the years",
> i.e. between 24th of December and 6th of January. For that, I would like
> to know *your* plans: what features or bugs do you feel have to go in
> or be fixed before the release?
>
> Thanks,
> Georg
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.19 (GNU/Linux)
>
> iEYEARECAAYFAlDFf+IACgkQN9GcIYhpnLBfOQCeKMUDQyh9XBzrdqXy8bktdZk9
> MOQAn3dlmEBbAX1XfEi7AtvPxVpvmsfC
> =4vFC
> -----END PGP SIGNATURE-----
--
> Kevin Hunter
> La Min Ko
> Nikolaj van Omme
> Robert Lehmann
> Roland Meister
> Takayuki Shimizukawa
>
> There has already been a lot of activity, and I am very thankful for
> that. And for those who have not been active yet, there is absolutely
> no obligation for anything, but please don't hesitate to write to this
> list if we can do something for you.
>
> I would like to get a version 1.2 out at some time "between the years",
> i.e. between 24th of December and 6th of January. For that, I would like
> to know *your* plans: what features or bugs do you feel have to go in
> or be fixed before the release?
>
> Thanks,
> Georg
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.19 (GNU/Linux)
>
> iEYEARECAAYFAlDFf+IACgkQN9GcIYhpnLBfOQCeKMUDQyh9XBzrdqXy8bktdZk9
> MOQAn3dlmEBbAX1XfEi7AtvPxVpvmsfC
> =4vFC
> -----END PGP SIGNATURE-----
Sam Kleinman (tychoish):
- ga...@tychoish.com
- tychoish <http://tychoish.com/>
"don't get it right, get it written" -- james thurber
Georg Brandl
Dec 17, 2012, 2:12:15 AM12/17/12
to sphin...@googlegroups.com
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hi Jon,
Hash: SHA1
Am 11.12.2012 10:46, schrieb Jonathan Waltman:
> On Mon, Dec 10, 2012 at 12:23 AM, Georg Brandl <ge...@python.org> wrote:
> ...
>> I would like to get a version 1.2 out at some time "between the years",
>> i.e. between 24th of December and 6th of January.
>
> Sounds goods.
>
> There was also some talk on Docutils 0.10 coming out soon, so we might get
> a little time to work against a stable release and catch any issues.
environment to tox.
>> For that, I would like to know *your* plans: what features or bugs do you
>> feel have to go in or be fixed before the release?
>
> These aren't by any means show stoppers but might be nice things to add.
>
> 1) Make autodoc easier to debug and customize.
In general, I think that a simple logger whose debugging messages you
can switch on with some command line flag would be appreciated by lots
of people.
Of course, that means going through the code and adding log.debug()
calls at places deemed worthy, not a pleasant task...
> Provide an easier way to access and manipulate live objects. Here are some
> ideas:
>
> Directly exec/eval code in the directives themselves:
>
> .. autofunction:: bar :exec: from other.mod import foo as bar
>
> Provide a new directive for executing blocks of code in a custom
> environment used to look up objects to document (similar to how the
> testsetup directive works in the doctest extension).
>
> .. autodocsetup:: ns
>
> from mod import * foo.__doc__ = process_doc(foo)
>
> .. autofunction:: foo :namespace: ns
> 2) Provide a way to get the intermediate reST generated by autodoc
> directives. Useful for debugging and actually seeing what the expanded
> form looks like.
> This could be just a configuration variable like `autodoc_debug_expanded`
> which causes each form to be printed whenever the directive is ran.
>
> More debugging flags in general would be nice to help people track down
> problems or understand what's going on with their docs.
>
> 3) sphinx-apidoc should work more like sphinx-autogen, in that it should
> analyze / import python source files and generate configurable output
> instead of just using `automodule`.
wishes of lots of people, but it is time that it is more fleshed out.
cheers,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
iEYEARECAAYFAlDOxc8ACgkQN9GcIYhpnLDKUACfWV6QVXuKAYpsEobbtJGvSzvI
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
DAkAn3Y6fqqgpBaU9QVojEsso8xom/Ix
=UkRM
-----END PGP SIGNATURE-----
Georg Brandl
Dec 17, 2012, 2:13:52 AM12/17/12
to sphin...@googlegroups.com
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hash: SHA1
Am 11.12.2012 15:54, schrieb Takayuki Shimizukawa:
> Hi there,
>
> 2012/12/10 Georg Brandl <ge...@python.org>:
>> I would like to get a version 1.2 out at some time "between the years",
>> i.e. between 24th of December and 6th of January. For that, I would
>> like to know *your* plans: what features or bugs do you feel have to go
>> in or be fixed before the release?
>
> I think there are several issues to reduce the availability of the Sphinx.
>
> :bugs: * i18n issues #940 #960 #975 #976 #1036
These could be important to fix, agreed.
> Hi there,
>
> 2012/12/10 Georg Brandl <ge...@python.org>:
>> I would like to get a version 1.2 out at some time "between the years",
>> i.e. between 24th of December and 6th of January. For that, I would
>> like to know *your* plans: what features or bugs do you feel have to go
>> in or be fixed before the release?
>
> I think there are several issues to reduce the availability of the Sphinx.
>
> :bugs: * i18n issues #940 #960 #975 #976 #1036
> :feature: * Human-readable objects.inv #1052 * Include anonymous label
> target in 'objects.inv' for intersphinx #1050
> i18n translation feature was introduced at Sphinx-1.1 release that is very
> important for multi-language documentation (e.g. sphinx-doc.org,
> docs.python.org ) but current Sphinx & docutils have several problems
> (above issues).
is a) ironing out bugs and b) telling others to use it :)
cheers,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
iEYEARECAAYFAlDOxjAACgkQN9GcIYhpnLBzWgCfcSMdhqG19f0PWIdAS1Y/650O
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
Z7gAoK09WF+WVCOVpRQkorDkw5Coilp9
=0ohb
-----END PGP SIGNATURE-----
Georg Brandl
Dec 17, 2012, 2:18:49 AM12/17/12
to sphin...@googlegroups.com
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hash: SHA1
Am 11.12.2012 16:40, schrieb Sam Kleinman:
>
> I'll root for my issues:
>
> -
> https://bitbucket.org/birkenfeld/sphinx/issue/880/cross-referencing-program-objects
>
>
- -
>
> I'll root for my issues:
>
> -
> https://bitbucket.org/birkenfeld/sphinx/issue/880/cross-referencing-program-objects
>
>
https://bitbucket.org/birkenfeld/sphinx/issue/1054/gettext-output-includes-restructured-text
>
> The first is an old one, that remains frustrating. There's no good way to
> index/reference objects for a (whole) binary, apart from indexing the
> command line options. Basically I want to be able to have a document that
> includes: ::
>
> :program:`sphinx-build`
>
> And have it link to the "man page" in my documentation for the sphinx-build
> executable.
Looks not too difficult to come up with a fix for this.
>
> The first is an old one, that remains frustrating. There's no good way to
> index/reference objects for a (whole) binary, apart from indexing the
> command line options. Basically I want to be able to have a document that
> includes: ::
>
> :program:`sphinx-build`
>
> And have it link to the "man page" in my documentation for the sphinx-build
> executable.
> The second is just a current annoyance with the PO output, that I've been
> meaning to bring up for a while...
Naively I would come to the same conclusion: let translators know about the
bit of markup that has to stay untranslated.
One thing that might be done is to check that the same roles appear both in
the msgid and the msgstr after translation, just like some po "compilers"
check the placeholders in format strings.
cheers,
Georg
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
iEYEARECAAYFAlDOx1kACgkQN9GcIYhpnLDYIQCgoQAvV6n5sDfDKJWOJYFu+AKe
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
3GsAn01PtM1c5/GMXi/LKLAI9ZldnvM/
=PMzH
-----END PGP SIGNATURE-----
Dmitry Shachnev
Jan 26, 2013, 4:18:17 AM1/26/13
to sphin...@googlegroups.com
Hi,
On Mon, Dec 10, 2012 at 12:23 AM, Georg Brandl <ge...@python.org> wrote:
> ...
> I would like to get a version 1.2 out at some time "between the years",
> i.e. between 24th of December and 6th of January.
Is there any new roadmap for the 1.2 release? Just so that I knew if I
(as a Debian/Ubuntu maintainer) should wait for it or backport some
fixes we are interested in…
P.S. I really like the new sphinx13 theme, thanks for adding it!
--
Dmitry Shachnev
On Mon, Dec 10, 2012 at 12:23 AM, Georg Brandl <ge...@python.org> wrote:
> ...
> I would like to get a version 1.2 out at some time "between the years",
> i.e. between 24th of December and 6th of January.
(as a Debian/Ubuntu maintainer) should wait for it or backport some
fixes we are interested in…
P.S. I really like the new sphinx13 theme, thanks for adding it!
--
Dmitry Shachnev
Takayuki Shimizukawa
Mar 28, 2013, 10:39:08 PM3/28/13
to sphin...@googlegroups.com, Georg Brandl
Hi Georg and developers,
Is there anything missing in order to release a new version?
March will end soon!
BTW, Japanese translation project of the Sphinx document was almost
finished except CHANGES.
The document is built and deployed automatically when there is an
update of the translation.
(transifex -[web push]-> drone.io (pull po from transifex, make html)
-[boto-rsync]-> s3 publish)
https://www.transifex.com/projects/p/sphinx-doc-1_2_0/
Regards,
2013/1/26 Dmitry Shachnev <mit...@ubuntu.com>:
Is there anything missing in order to release a new version?
March will end soon!
BTW, Japanese translation project of the Sphinx document was almost
finished except CHANGES.
The document is built and deployed automatically when there is an
update of the translation.
(transifex -[web push]-> drone.io (pull po from transifex, make html)
-[boto-rsync]-> s3 publish)
https://www.transifex.com/projects/p/sphinx-doc-1_2_0/
Regards,
2013/1/26 Dmitry Shachnev <mit...@ubuntu.com>:
Georg Brandl
Mar 29, 2013, 5:52:40 AM3/29/13
to sphin...@googlegroups.com
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hi,
Hash: SHA1
I know -- I have a few free days now around Easter, where I planned to
release a beta version.
Great to hear about the Japanese translation. Is there anything we can
add to the docs for those who want to use a similar workflow?
cheers,
Georg
>>
>> P.S. I really like the new sphinx13 theme, thanks for adding it!
>>
>> -- Dmitry Shachnev
>
>> P.S. I really like the new sphinx13 theme, thanks for adding it!
>>
>> -- Dmitry Shachnev
>
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.19 (GNU/Linux)
iEYEARECAAYFAlFVZGgACgkQN9GcIYhpnLBkkQCgh3Df2MqE55gi7Lu0htMp95KS
Version: GnuPG v2.0.19 (GNU/Linux)
/OsAoKvhyujndR1vsLvObUHaP4Z3A79L
=P16s
-----END PGP SIGNATURE-----
Takayuki Shimizukawa
Mar 29, 2013, 11:59:44 AM3/29/13
to sphin...@googlegroups.com
Hi Georg,
> Is there anything we can
> add to the docs for those who want to use a similar workflow?
Ok, I'm going to write first draft document.
(and please correct my English... ;-(
FYI, drone.io's build script is here:
https://drone.io/bitbucket.org/shimizukawa/sphinx-transifex/admin
2013/3/29 Georg Brandl <ge...@python.org>:
>>> we are interested in…
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>
> Is there anything we can
> add to the docs for those who want to use a similar workflow?
(and please correct my English... ;-(
FYI, drone.io's build script is here:
https://drone.io/bitbucket.org/shimizukawa/sphinx-transifex/admin
2013/3/29 Georg Brandl <ge...@python.org>:
>>>
>>> P.S. I really like the new sphinx13 theme, thanks for adding it!
>>>
>>> -- Dmitry Shachnev
>>
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.19 (GNU/Linux)
>
> iEYEARECAAYFAlFVZGgACgkQN9GcIYhpnLBkkQCgh3Df2MqE55gi7Lu0htMp95KS
> /OsAoKvhyujndR1vsLvObUHaP4Z3A79L
> =P16s
> -----END PGP SIGNATURE-----
>
> --
>>> P.S. I really like the new sphinx13 theme, thanks for adding it!
>>>
>>> -- Dmitry Shachnev
>>
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2.0.19 (GNU/Linux)
>
> iEYEARECAAYFAlFVZGgACgkQN9GcIYhpnLBkkQCgh3Df2MqE55gi7Lu0htMp95KS
> /OsAoKvhyujndR1vsLvObUHaP4Z3A79L
> =P16s
> -----END PGP SIGNATURE-----
>
> You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+...@googlegroups.com.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>
Takayuki Shimizukawa
Apr 2, 2013, 11:16:48 AM4/2/13
to sphin...@googlegroups.com
Hi
2013/3/30 Takayuki Shimizukawa <shimi...@gmail.com>:
https://bitbucket.org/birkenfeld/sphinx/src/e199e0a/doc/translationguide.rst?at=default
and I plan to write some more.
2013/3/30 Takayuki Shimizukawa <shimi...@gmail.com>:
> Hi Georg,
>
>> Is there anything we can
>> add to the docs for those who want to use a similar workflow?
>
> Ok, I'm going to write first draft document.
> (and please correct my English... ;-(
I pushed a first draft of translation guide.
>
>> Is there anything we can
>> add to the docs for those who want to use a similar workflow?
>
> Ok, I'm going to write first draft document.
> (and please correct my English... ;-(
https://bitbucket.org/birkenfeld/sphinx/src/e199e0a/doc/translationguide.rst?at=default
and I plan to write some more.
Robert Lehmann
Apr 3, 2013, 5:04:22 AM4/3/13
to sphin...@googlegroups.com
How's this document related to doc/intl.rst [1] (I feel they kinda have the same goal,) and should they probably be merged? Also, can we make this process easier in any regard?
Reply all
Reply to author
Forward
0 new messages