Building Sphinx docs on Windows

wxPython Dev
#1

Hi,

I have been chasing a few bugs/issues and trying to improve the automatically generated Sphinx docs. I have made a few fixes on my fork of Phoenix, but I am encountering a slight bump. The docs simply don’t build on Windows - I mean, I get the html files, but Sphinx generates more than 60,000 warnings, most of them related to images it can’t find.

Sample of warning message:

headings.inc:195: WARNING: image file not readable: _staticimagessphinxdocsmodule_summary.png

Which is kind of funny as the actual declaration is:

… |module_summary| image:: _static\images\sphinxdocs\module_summary.png

:align: middle

:width: 32px

Looks like all the path separators are stripped out…

Anyone else seeing this?

This is on Windows 10, Python 2.7.11, Sphinx 1.5.5.

Andrea.

#2

With sphinx I'm using / as path separator, also on Windows.

Maybe \\ would work, but using / is probably the best solution.

Regards,

Dietmar

···

On 11/12/2017 7:10 PM, Andrea Gavana wrote:

Which is kind of funny as the actual declaration is:

.. |module_summary| image:: _static\images\sphinxdocs\module_summary.png
:align: middle
:width: 32px

#3

Or make sure the doc strings are all raw strings:

def thing(xyz):

r"""

c:\somewhere

“”"

···

On Sun, Nov 12, 2017 at 10:43 AM, Dietmar Schwertberger maillist@schwertberger.de wrote:

Which is kind of funny as the actual declaration is:

… |module_summary| image:: _static\images\sphinxdocs\module_summary.png

:align: middle

:width: 32px

On 11/12/2017 7:10 PM, Andrea Gavana wrote:

With sphinx I’m using / as path separator, also on Windows.

Maybe \ would work, but using / is probably the best solution.

Regards,

Dietmar

–

You received this message because you are subscribed to the Google Groups “wxPython-dev” group.

To unsubscribe from this group and stop receiving emails from it, send an email to wxPython-dev+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

#4

Oops. But I would (and do) as Dietmar suggests and avoid backslashes altogether, only ever use slash as a file separator.

···

On Sun, Nov 12, 2017 at 12:24 PM, Eric Fahlgren ericfahlgren@gmail.com wrote:

Or make sure the doc strings are all raw strings:

def thing(xyz):

r"""

c:\somewhere

“”"

On Sun, Nov 12, 2017 at 10:43 AM, Dietmar Schwertberger maillist@schwertberger.de wrote:

Which is kind of funny as the actual declaration is:

… |module_summary| image:: _static\images\sphinxdocs\module_summary.png

:align: middle

:width: 32px

On 11/12/2017 7:10 PM, Andrea Gavana wrote:

With sphinx I’m using / as path separator, also on Windows.

Maybe \ would work, but using / is probably the best solution.

Regards,

Dietmar

–

You received this message because you are subscribed to the Google Groups “wxPython-dev” group.

To unsubscribe from this group and stop receiving emails from it, send an email to wxPython-dev+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

#5

Or make sure the doc strings are all raw strings:

def thing(xyz):

r"""

c:\somewhere

“”"

No, that’s not the issue. I wrote half of the code that converts the wxWidgets docs into Phoenix ones, a few years back. And it was still working not long ago.

Andrea.

···

On Sun, Nov 12, 2017 at 10:43 AM, Dietmar Schwertberger maillist@schwertberger.de wrote:

Which is kind of funny as the actual declaration is:

… |module_summary| image:: _static\images\sphinxdocs\module_summary.png

:align: middle

:width: 32px
On 11/12/2017 7:10 PM, Andrea Gavana wrote:

With sphinx I’m using / as path separator, also on Windows.

Maybe \ would work, but using / is probably the best solution.

Regards,

Dietmar

–

You received this message because you are subscribed to the Google Groups “wxPython-dev” group.

To unsubscribe from this group and stop receiving emails from it, send an email to wxPython-dev+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

#6

The sphinx installation that I have certainly does not work with a backslash in the file name. Single slash or double backslash are working. I would suggest to modify the conversion code to use slashes.

Regards,

Dietmar

···

On 11/12/2017 9:30 PM, Andrea Gavana wrote:

No, that’s not the issue. I wrote half of the code that converts the wxWidgets docs into Phoenix ones, a few years back. And it was still working not long ago.

#7

Hi Dietmar,

No, that’s not the issue. I wrote half of the code that converts the

wxWidgets docs into Phoenix ones, a few years back. And it was still

working not long ago.

The sphinx installation that I have certainly does not work with a

backslash in the file name. Single slash or double backslash are

working. I would suggest to modify the conversion code to use
slashes.

I perfectly understand what you wrote, what I’m puzzled about is that the very same code (as far as I can see) used to work a few months back with no modifications. I’ll dig into the docstrings generation code to see if anything has changed since then.

Andrea.

···

On Sun, 12 Nov 2017 at 21.42, Dietmar Schwertberger maillist@schwertberger.de wrote:

On 11/12/2017 9:30 PM, Andrea Gavana wrote:

Regards,

Dietmar

–

You received this message because you are subscribed to the Google Groups “wxPython-dev” group.

To unsubscribe from this group and stop receiving emails from it, send an email to wxPython-dev+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

#8

Hi Andrea,

The dist-docs builder on the buildbot is running on a Windows machine, so you may want to look at the logs for recent builds there to see if it gives you any clues. One thing that comes to mind is that Sphinx and its dependencies hasn’t been updated there in a long time, so it may be related to you using a newer version of Sphinx or other packages.

http://buildbot.wxpython.org/waterfall

Robin

···

On Sunday, November 12, 2017 at 9:14:28 PM UTC-8, Infinity77 wrote:

Hi Dietmar,

On Sun, 12 Nov 2017 at 21.42, Dietmar Schwertberger maillist@schwertberger.de wrote:

On 11/12/2017 9:30 PM, Andrea Gavana wrote:

No, that’s not the issue. I wrote half of the code that converts the

wxWidgets docs into Phoenix ones, a few years back. And it was still

working not long ago.

The sphinx installation that I have certainly does not work with a

backslash in the file name. Single slash or double backslash are

working. I would suggest to modify the conversion code to use
slashes.

I perfectly understand what you wrote, what I’m puzzled about is that the very same code (as far as I can see) used to work a few months back with no modifications. I’ll dig into the docstrings generation code to see if anything has changed since then.

Andrea.

Regards,

Dietmar

–

You received this message because you are subscribed to the Google Groups “wxPython-dev” group.

To unsubscribe from this group and stop receiving emails from it, send an email to wxPython-dev+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

#9

Ran into same issue. Fixed in Github commit. Should be in next release.

Thanks Robin!

···

On Monday, 13 November 2017 12:38:10 UTC-5, Robin Dunn wrote:

Hi Andrea,

The dist-docs builder on the buildbot is running on a Windows machine, so you may want to look at the logs for recent builds there to see if it gives you any clues. One thing that comes to mind is that Sphinx and its dependencies hasn’t been updated there in a long time, so it may be related to you using a newer version of Sphinx or other packages.

http://buildbot.wxpython.org/waterfall

Robin

On Sunday, November 12, 2017 at 9:14:28 PM UTC-8, Infinity77 wrote:

Hi Dietmar,

On Sun, 12 Nov 2017 at 21.42, Dietmar Schwertberger mail...@schwertberger.de wrote:

On 11/12/2017 9:30 PM, Andrea Gavana wrote:

No, that’s not the issue. I wrote half of the code that converts the

wxWidgets docs into Phoenix ones, a few years back. And it was still

working not long ago.

The sphinx installation that I have certainly does not work with a

backslash in the file name. Single slash or double backslash are

working. I would suggest to modify the conversion code to use
slashes.

I perfectly understand what you wrote, what I’m puzzled about is that the very same code (as far as I can see) used to work a few months back with no modifications. I’ll dig into the docstrings generation code to see if anything has changed since then.

Andrea.

Regards,

Dietmar

–

You received this message because you are subscribed to the Google Groups “wxPython-dev” group.

To unsubscribe from this group and stop receiving emails from it, send an email to wxPython-dev...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.