#sphinx-doc

nano-: "emit stuff"?

nano-: usually i just ask questions, if people find the question interesting they'll answer

ngoldbaum: Yes, I can dig out symbols that I want to emit "autoattribute" directives for. I was hoping I could do this via a sphinx extension, so I just type ".. myconstgeneratorthingie::" in my .rst file and the extension takes constants of that script and produces autoattribute for each one. If it's not possible to depend on other extensions (autodoc in this case), then at least attribute:: with :annotation: ought to be possible to emit to ...

... produce the same thing?

oh, forgot to include paste, here is an example of how I can dig out symbols sphinx will not include automatically, http://90555e844d02d5df.paste.se/

ngoldbaum: I've tried to play around with addnodes.desc* methods, if I understand addnodes.desc_addname should be used for the module, and addnodes.desc_name for the constant, but I don't get any '.' between the module and the constant, should I add that as the first character in the constant? Also, they will not be crossreferable from the rest of my documentation via `VALUE_TYPE_NONE` for example, with default_role='any'.

The rest of the documentation is extracted via autoclass directives.

Another option would be to have my build system generate a rst file containing .. autoattribute:: for each constant, but that's almost as hacky as writing such a file on my own.

I just can't figure out how to emit a reference from a directive

does the directive have to resolve it (if so which method), or does it emit a node and a later step links it (if so which node & arguments)

I'd like the standard handling fall back to text and emit a warning if the target does not exist

ideally I just want a simple; make_ref(role, id) style method that returns a node

so then :ref:`test` would be; node = nodes.block_quote(); node += make_ref('ref', 'test'); return [node]

ngoldbaum: oh.. and my current attempts are being made via function passed to app.add_object_type(...., parse_node=mycurrentattempt)

ok, I have something that sort of works, but it just seems wrong

there must be some way to resolve `ref` and avoid the `ref = env.domains['std'].roles['ref']` section

ok, I've gotten closer, this looks correct though I'm not sure what I'm supposed to be doing with messages, https://gist.github.com/chilversc/a30aa0ee5fa8f...

is there any documentation on this? as I couldn't see anything on the sphinx or docutils site

is there any simple method to just dump an object graph (ignoring methods, not following cycles, not erroring on unknown objects)?

sorry, ment to ask this in python

chilversc: i've done this before, let me try to find the name of the library i used

chilversc: ^

its more the values I'm interested in, so something like a json dump (trying to explore the various return types from the different sphinx methods)

I'm finding the sphinx docs quite difficult to follow once I get in to the api as they are missing all the apis around directives etc (that come from docutils)

ah, i don't think sphinx internals are documented particularly well

and I just can't find the docutils api documenation anywhere

it's people cribbing off of other people's hacks all the way down

chivlversc: I just found them last night http://epydoc.sourceforge.net/docutils/private/...

also, this http://docutils.readthedocs.org/en/sphinx-docs/...

ngoldbaum: any idea?

nano-: sorry, i didn't look at your messages, i left before you sent them to me

np, i'll collect them.

ngoldbaum: http://ca3158436141422c.paste.se/

nano-: are you aware that sphinx can do this sort of stuff for you?

unless i'm misunderstanding what you're going for

nano-: look for sphinx.ext.autosummary

it can automatically generate API docs

It can't it will not emit for imports.

ah, then you're getting into dark and scary territory

Well.. not really. I don't have to have sphinx know about imports. I just need to write an extension that emits arbitrary sphinx syntax that documentation generated via autoclass can refer to via `SOMECONST` when the default_role is 'any', just like it would be able to if I added a .. autoattribute:: SOMECONST

So I hope writing extensions isn't dark and scary. That doesn't make sense :)

nano-: it kind of is

you need to know sphinx and docutils internals

it's best if whatever you're trying to do is simple enough that you don't need to look at that stuff

Ok.. so then I guess a python script that preprocesses the .rst file to append the .. autoattribute:: will have to do then.

hacky, but works.