Hi Neil, Unfortunately, I think there is no feature you would expect.
If you will implement the extension and you want to annotate the description for each *files* (not for each section), I think `docinfo` like extension might be easy to use. http://sphinx-doc.org/markup/misc.html#file-wide-metadata white_paper_001.rst:: :abstract: This white paper explains the relationship between X and Y. =============== White Paper 001 =============== And, metadata that is generated from docinfo is easy to manage / implementation than directive. https://bitbucket.org/birkenfeld/sphinx/src/4e3310a/sphinx/environment.py#cl-1668 If you want to implement a extension as a directive, I think the 'sphinx.ext.todo' directive code will help you. https://bitbucket.org/birkenfeld/sphinx/src/4e3310a/sphinx/ext/todo.py Regards, -- Takayuki SHIMIZUKAWA http://about.me/shimizukawa 2014-04-24 22:38 GMT+09:00 Neil K <[email protected]>: > I have had a good hunt around looking for the ability to define per file an > 'abstract' / 'summary' that I can then have displayed in a toctree but have > come up blank. What I am looking for is something akin to the > autosummary/docstring approach but not quite. Does this exist? Have I missed > it somewhere? Maybe I will have to create my own directive but thought I > would ask first. > > To be clear about what I am looking for I have a outlined an example below. > > Lets say I have a file called white_paper_001.rst that looks like this - > they part being the abstract is defined so that it can be used: > > =============== > White Paper 001 > =============== > > .. abstract:: > This white paper explains the relationship between X and Y. > > Body text will go here .... > > > In my index.rst I would have something like this - identifying that I want > the abstract included in the listing in much the same way as the > :titlesonly:option tells sphinx to display the titles: > > ============ > White Papers > ============ > > Contents: > > .. toctree:: > :glob: > > :abstract: > > > white_papers/* > > > Ideally I would then get something like the following - the key here is that > the abstract is sourced from the file itself rather than keyed in > independently on index.rst: > > White Papers > > > > White Paper 001 > > This white paper explains the relationship between X and Y. > > > > White Paper 002 > > This white paper explains the key concepts around ABC. > > -- > 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 http://groups.google.com/group/sphinx-users. > For more options, visit https://groups.google.com/d/optout. -- 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 http://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
