How to debug custom extensions in Python

[Dirk Baumbach]

Hello,

i want to develop a custom Sphinx extension, mentioned in another topic here.

I want to use the 'raw' node as basis, but sadly the ddocumentation for the raw node is not very extensive:

http://docutils.sourceforge.net/docs/ref/doctree.html#raw

For a start i just want to know how i can debug Sphinx.

I created the following code snippet:

class ConfluencePageDirective(Directive):

    def run(self):

        confluence_text = GetConfluencePage()

        raw_node = nodes.raw(confluence_text) #(text='This is the audi confluence plugin!')

        return [raw_node]

Now i want to set a breakpoint at the line:

        raw_node = nodes.raw(confluence_text) #(text='This is the audi confluence plugin!')

To look what is inside the raw node.

Which python command must i use, to start a sphinx build, so i can debug to this point?

I guess if I run Sphinx over the command line, there is no way to debug.

So far,

Dirk

[Kevin Sheppard]

I use PyCharm to debug Sphinx-related projects:

I copy the sphinx runner script:

# -*- coding: utf-8 -*-

import re

import sys

from sphinx.cmd.build import main

if __name__ == "__main__":

    sys.argv[0] = re.sub(r"(-script\.pyw?|\.exe)?$", "", sys.argv[0])

    sys.exit(main())

And then I run it in the debugger with the options -b html -d _build/doctrees   . _build/html

Finally, I set the working directory to the location of my docs (where the Makefile resides)

[Dirk Baumbach]

Hello,

this worked so far. But my breakpoint was not hit. I guess i will create a minimal working example to work with, when there is time.

But thank you so far!

[Kevin Sheppard]

You might want to set a break point in a sphinx function that you know is hit. It is possible that your breakpoint in your extension isn't being run. 

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/1a61c9dd-900a-4394-b883-30dcdc0978ec%40googlegroups.com.

[Dirk Baumbach]

Hello,

yeah this was it. Thank you!

Am Dienstag, 15. Oktober 2019 13:11:07 UTC+2 schrieb Kevin Sheppard:

You might want to set a break point in a sphinx function that you know is hit. It is possible that your breakpoint in your extension isn't being run. 

On Tue, Oct 15, 2019, 11:51 Dirk Baumbach <d.bau...@gmail.com> wrote:

Hello,

this worked so far. But my breakpoint was not hit. I guess i will create a minimal working example to work with, when there is time.

But thank you so far!

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.

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

[Paul Everitt]

Apologies, late to the party. My "Customizing Sphinx: Simple, Normal, Hard" talks end with writing an extension using TDD and debugging.

If you're writing an extension, I highly-highly recommend doing it via tests instead of via "code, run, reload browser, curse". The pytest fixture is really handy. And in PyCharm (including the free version), it's easy to use the visual test runner and visual debugger together.

Alas, I don't think there's much demand for Sphinx extension how-to's, otherwise I'd give it full treatment.