Sorry, you are right, this is all over the place. I understand now what
option_spec does. I'm right now trying to understand the run method of
modules.
The env variable is the first mystery, I understand it encapsulates the
entire "environment", but that's a pretty nebulous term. I'm guessing it's
of type Sphinx.environment.BuildEnvironment. We use it three times: once
setting a dictionary entry in ref_context, once setting a dictionary entry
in domaindata and once reading the docname.
env.ref_context['py:module'] = modname
What does this do, or rather what is the purpose? When should I do it and
when should I not?
env.domaindata['py']['modules'][modname] = \
(env.docname, self.options.get('synopsis', ''),
self.options.get('platform', ''), 'deprecated' in self.options)
# make a duplicate entry in 'objects' to facilitate searching for
# the module in PythonDomain.find_obj()
env.domaindata['py']['objects'][modname] = (env.docname, 'module')
I understand why we do it twice, we register the module as a regular module
first, and as an object second, so it appears in two places. The question
is, what is the type of objects in domaindata? It not used anywhere else in
the script, so it looks like magic. Related question, what is env.docname?
The next few lines are
targetnode = nodes.target('', '', ids=['module-' + modname],
ismod=True)
self.state.document.note_explicit_target(targetnode)
# the platform and synopsis aren't printed; in fact, they are only
# used in the modindex currently
ret.append(targetnode)
indextext = _('%s (module)') % modname
inode = addnodes.index(entries=[('single', indextext,
'module-' + modname, '')])
ret.append(inode)
>From what I gather from the Docutils documentation we want to return a list
of nodes from the run method that will be inserted into the document tree
at the point where the directive is encountered. Correct? The target node
class if from Docutils and has no docstring, so I have no clue wha it does.
How did anyone figure that out? The second on I do understand, it's
basically faking a .. index directive. What does the four parameter ignored
do?
If I were to make a guess I would say that the target node does nothing, it
just sits in the tree so the index can find it based on the ids parameter.
How does the index module get moved to the index, is that done by Sphinx
automatically?
Thanks for your time.
On Wednesday, February 17, 2016 at 4:54:06 AM UTC+1, gsavix wrote:
>
> hi. please lets step by step. could you please divide your questions? make
> 1 at time and divide your issue with clear examples (for example see gammu (
> http://wammu.eu/) that use c, python, bash, windows, look at sources and
> try to build manual html. then you will get quick answers.
> regards.
>
--
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 [email protected].
To post to this group, send email to [email protected].
Visit this group at https://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/d/optout.
