Mercurial > p > roundup > code
changeset 8263:78b13272d41b
docs: link to Client and TemplatingUtils class/method docstrings
pydoc.txt:
new page. Has two example autodoc invocations: automethod and autoclass.
docs.txt
Added pydoc.txt as a hidden page in a new toc in docs.txt. Added
includehidden in toc directive.Not sure what it does, but was part
of a recipie to hide the pydoc from the main TOC.
conf.py:
added sphinx.ext.autodoc to get it pulling in the docs.
reference.txt:
added references to the pydoc using :py:meth: for templating utils
methods like set-http_response and :py:class: for Client as the
existing docs referenced the docstrings.
Changed table formatting for the TemplatingUtils methods from table
to list-table. The length of the references to the methods was too
large to exist in the first column of a drawn table.
For right now the pydoc stuff is only referenced via links from the
main docs. Currently it is ugly, but the additional info on tempating
utils and their arguments can be helpful.
Added sphin
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Tue, 07 Jan 2025 23:00:35 -0500 |
| parents | 2a7c3eeaf167 |
| children | 09e8d1a4c796 |
| files | doc/pydoc.txt doc/reference.txt website/www/conf.py website/www/docs.txt |
| diffstat | 4 files changed, 62 insertions(+), 25 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/pydoc.txt Tue Jan 07 23:00:35 2025 -0500 @@ -0,0 +1,17 @@ +================ +Pydocs from code +================ + +.. contents:: + :local: + +Client class +============ + +.. autoclass:: roundup.cgi.client::Client + +Templating Utils class +====================== + +.. autoclass:: roundup.cgi.templating::TemplatingUtils + :members:
--- a/doc/reference.txt Tue Jan 07 20:22:33 2025 -0500 +++ b/doc/reference.txt Tue Jan 07 23:00:35 2025 -0500 @@ -1745,7 +1745,7 @@ (``ZRoundup`` is broken, until further notice). In all cases, Roundup determines which tracker is accessed (the first part of the URL path inside the scope of the CGI handler) and pass control on to the -``roundup.cgi.client.Client`` class - which handles the rest of the +:py:class:`roundup.cgi.client.Client` class - which handles the rest of the access through its ``main()`` method. This means that you can do pretty much anything you want as a web interface to your tracker. @@ -3467,26 +3467,38 @@ ``roundup.cgi.templating.TemplatingUtils`` class. New methods can be added to the variable by using extensions_. -.. table:: - :class: valign-top - - ================= ======================================================== - Method Description - ================= ======================================================== - Batch return a batch object using the supplied list - anti_csrf_nonce returns the random nonce generated for this session - expandfile load a file into a template and expand - '%(tokenname)s' in the file using - values from the supplied dictionary. - html_quote quote some text as safe in HTML (ie. <, >, ...) - html_calendar renders an HTML calendar used by the - ``_generic.calendar.html`` template (itself invoked by - the popupCalendar DateHTMLProperty method - readfile read JavaScript or other content in an external - file into the template. - set_http_response sets the HTTP response code for the request. - url_quote quote some text as safe for a URL (ie. space, %, ...) - ================= ======================================================== +----- + +.. list-table:: TemplatingUtils Methods + :align: left + :header-rows: 1 + :class: valign-top captionbelow booktabs + + * - Method + - Description + * - Batch + - return a batch object using the supplied list + * - anti_csrf_nonce + - returns the random nonce generated for this session + * - :meth:`expandfile <roundup.cgi.templating.TemplatingUtils.expandfile>` + - load a file into a template and expand + '%(tokenname)s' in the file using + values from the supplied dictionary. + * - :meth:`html_calendar <roundup.cgi.templating.TemplatingUtils.html_calendar>` + - renders an HTML calendar used by the ``_generic.calendar.html`` + template (itself invoked by the popupCalendar DateHTMLProperty + method + * - :meth:`html_quote <roundup.cgi.templating.TemplatingUtils.html_quote>` + - quote some text as safe in HTML (ie. <, >, ...) + * - :meth:`readfile <roundup.cgi.templating.TemplatingUtils.readfile>` + - read JavaScript or other content in an external file + into the template. + * - :meth:`set_http_response <roundup.cgi.templating.TemplatingUtils.set_http_response>` + - set_http_response sets the HTTP response code for the request. + * - :meth:`url_quote <roundup.cgi.templating.TemplatingUtils.url_quote>` + - quote some text as safe for a URL (ie. space, %, ...) + +----- Additional info can be obtained by starting ``python`` with the ``roundup`` subdirectory on your PYTHONPATH and using the Python help @@ -3960,7 +3972,8 @@ ''' The *self.client* attribute is an instance of ``roundup.cgi.client.Client``. -See the docstring of that class for details of what it can do. +See the :class:`docstring of that class <roundup.cgi.client.Client>` +for details of what it can do. The method will typically check the ``self.form`` variable's contents. It may then:
--- a/website/www/conf.py Tue Jan 07 20:22:33 2025 -0500 +++ b/website/www/conf.py Tue Jan 07 23:00:35 2025 -0500 @@ -45,9 +45,10 @@ # General configuration # --------------------- -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ["sphinxext.opengraph", 'sphinx_sitemap', 'sphinx_tabs.tabs',] +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinxext.opengraph', + 'sphinx_sitemap', 'sphinx_tabs.tabs'] sphinx_tabs_valid_builders = ['linkcheck'] sphinx_tabs_disable_tab_closing = True
--- a/website/www/docs.txt Tue Jan 07 20:22:33 2025 -0500 +++ b/website/www/docs.txt Tue Jan 07 23:00:35 2025 -0500 @@ -20,6 +20,7 @@ .. toctree:: :maxdepth: 2 + :includehidden: Features <docs/features> Installation <docs/installation> @@ -37,3 +38,8 @@ docs/license docs/acknowledgements olderdocs + +.. toctree:: + :hidden: + + docs/pydoc