Thread: [Epydoc-devel] Documentation not associated with a particular module, function, class, or method
Brought to you by:
edloper
From: Joseph T. <tu...@gm...> - 2008-02-26 23:55:35
|
I am understanding someone else's code, and helping to document it as I understand it. The author was explaining to me and using the term "graph". Graph is not actually a particular module, function, class, or method. It is just an umbrella concept tying together a lot of things. We are trying to write documentation for the "graph" concept. We would prefer to write it using epytext markup (as opposed to independent HTML documentation) so that links to epydoc-generated HTML is created. What is the best way to do this? Do I have to make a dummy documentation module graph.py, or is there a more elegant approach? Thanks, Joseph -- Academic: http://www-etud.iro.umontreal.ca/~turian/ Business: http://www.metaoptimize.com/ |
Re: [Epydoc-devel] Documentation not associated with a particular
module, function, class, or method
From: Edward L. <ed...@se...> - 2008-02-27 01:01:41
|
If you just want to convert stand-alone epytext to html, it's not too hard. But if you want it to include links into the documentation generated by epydoc, then things get a bit trickier. The code following this email should do basically what you want -- it runs the epydoc command line interface (with options taken from sys.argv), and then has some code at the end to parse a text file containing epytext material (linking it to the docs), and write it as html to the output directory. It's a bit hackish, though, I'm afraid. A better solution would probably be to add the ability for epydoc to read files containing epytext (or rst) and convert them natively.. something like: % epydoc my_package/ --rst-file my_docfile.rst --epytext-file my_other_docfile.txt Some issues might have to be worked out though, such as what files they would be written to in the output, whether they could get referenced by docstrings in python code, etc. -Edward ======================================================== import epydoc.cli, os.path from epydoc.markup.epytext import ParsedEpytextDocstring, pparse from epydoc.docwriter.html import HTMLWriter # Run epydoc. options = epydoc.cli.parse_arguments() docindex = epydoc.cli.main(options) html_writer = HTMLWriter(docindex, **options.__dict__) html_writer._directory = options.target['html'] TEMPLATE = "<html><head>Hello</head><body>%s</body></html>" # Convert my own file. doc = ParsedEpytextDocstring(pparse(open('foo.txt').read())) out = open(os.path.join(options.target['html'], 'foo.html'), 'w') out.write(TEMPLATE % html_writer.docstring_to_html(doc)) out.close() |
Re: [Epydoc-devel] Documentation not associated with a particular
module, function, class, or method
From: Joseph T. <tu...@gm...> - 2008-02-27 00:54:56
|
I guess I was thinking something along the lines of the Doxygen \page command: http://www.stack.nl/~dimitri/doxygen/commands.html#cmdpage " Indicates that a comment block contains a piece of documentation that is not directly related to one specific class, file or member. The HTML generator creates a page containing the documentation. The [image: $\mbox{\LaTeX}$] generator starts a new section in the chapter `Page documentation'." If you just want to convert stand-alone epytext to html, it's not too > hard. But if you want it to include links into the documentation > generated by epydoc, then things get a bit trickier. Yeah, I wanted the tricky thing :^) The code following this email should do basically what you want -- it > runs the epydoc command line interface (with options taken from > sys.argv), and then has some code at the end to parse a text file > containing epytext material (linking it to the docs), and write it as > html to the output directory. It's a bit hackish, though, I'm afraid. I wasn't able to figure out how to invoke this code. Does it provide links to and from graph? That's what I need. A better solution would probably be to add the ability for epydoc to > read files containing epytext (or rst) and convert them natively.. > something like: > > % epydoc my_package/ --rst-file my_docfile.rst --epytext-file > my_other_docfile.txt That sounds great. Ideally, I could do: --epytext-file extra/*.txt Some issues might have to be worked out though, such as what files > they would be written to in the output, whether they could get > referenced by docstrings in python code, etc. Instead of -module -pysrc or -class, just use -page (as does doxygen). They should definitely be able to reference and be referenced by docstrings in the python code. The idea for "page" is to be able to describe general concepts and design decisions, and link to them in docstrings as needed. Thanks, Joseph -- Academic: http://www-etud.iro.umontreal.ca/~turian/ Business: http://www.metaoptimize.com/ |
Re: [Epydoc-devel] Documentation not associated with a particular
module, function, class, or method
From: Daniele V. <pi...@de...> - 2008-02-27 08:32:04
|
Joseph Turian ha scritto: > I am understanding someone else's code, and helping to document it as I > understand it. > The author was explaining to me and using the term "graph". Graph is not > actually a particular module, function, class, or method. > It is just an umbrella concept tying together a lot of things. > > We are trying to write documentation for the "graph" concept. > We would prefer to write it using epytext markup (as opposed to > independent HTML documentation) so that links to epydoc-generated HTML > is created. Have you considered the use of reStructuredText syntax to produce your documentation? Just like epytext it can be used to produce API documentation with Epydoc, but it is already geared towards the production of standalone documents too (with titles, ToC, metadata etc.) and is ready to produce html, pdf and some other fancy format. Epydoc also contains a script - apirst2html.py - allowing a standalone reST document to reference API docs generated with Epydoc itself, e.g. citing :api:`some_function()` or :api:`module.Class`. The script converts the document into HTML and links the objects marked with the above syntax to the matching epydoc-generated API docs. -- Daniele Varrazzo - Develer S.r.l. http://www.develer.com |
Re: [Epydoc-devel] Documentation not associated with a particular
module, function, class, or method
From: Joseph T. <tu...@gm...> - 2008-02-27 18:00:07
|
Daniele, Have you considered the use of reStructuredText syntax to produce your > documentation? I did consider it, but I am not sure if it solves our usage requirements. Maybe you can help? > Just like epytext it can be used to produce API documentation > with Epydoc, but it is already geared towards the production of standalone > documents too (with titles, ToC, metadata etc.) and is ready to produce > html, > pdf and some other fancy format. Okay. But how do I create a standalone document about the "graph" concept and then, within the code main code, link to the "graph" concept using @see or L{graph}? This is what I couldn't figure out. Epydoc also contains a script - apirst2html.py - allowing a standalone reST > document to reference API docs generated with Epydoc itself, e.g. citing > :api:`some_function()` or :api:`module.Class`. The script converts the > document into HTML and links the objects marked with the above syntax to > the > matching epydoc-generated API docs. What about linking from epydoc comments to the standalone reST? Is there a clean approach (not just hardcoding an external URL)? Thanks, Joseph -- Academic: http://www-etud.iro.umontreal.ca/~turian/ Business: http://www.metaoptimize.com/ |
Re: [Epydoc-devel] Documentation not associated with a particular
module, function, class, or method
From: Daniele V. <pi...@de...> - 2008-02-28 15:41:44
|
Joseph Turian ha scritto: > Daniele, > > I did consider it, but I am not sure if it solves our usage requirements. > Maybe you can help? > > [...] > Okay. But how do I create a standalone document about the "graph" > concept and then, within the code main code, link to the "graph" concept > using @see or L{graph}? This is what I couldn't figure out. Mmm... no, you are right. Currently i don't think there is a way to reference external documentation if not with a full url. Epytext instead has a nice feature that may help you: indexed terms: http://epydoc.sourceforge.net/manual-epytext.html#indexed-terms You can define a graph in a module docstring and refer to it even without creating dummy python objects. -- Daniele Varrazzo - Develer S.r.l. http://www.develer.com |
Re: [Epydoc-devel] Documentation not associated with a particular
module, function, class, or method
From: Joseph T. <tu...@gm...> - 2008-02-28 21:06:50
|
> Epytext instead has a nice feature that may help you: indexed terms: > > http://epydoc.sourceforge.net/manual-epytext.html#indexed-terms > > You can define a graph in a module docstring and refer to it even without > creating dummy python objects. > Thanks for the suggestions. Unfortunately, I already tried indexed terms and they don't work. In particular, I cannot L{graph} to link to the indexed term. Any more ideas? Or is this a genuine new feature that needs to be implemented? Thanks, Joseph -- Academic: http://www-etud.iro.umontreal.ca/~turian/ Business: http://www.metaoptimize.com/ |