Standard HTML tags
The following tags should be usable just as they are in regular HTML:
a, abbr, acronym, address, applet, area, article, aside, audio, b, basefont, bdi, bdo, big, blink, blockquote, br, button, canvas, caption, center, cite, code, col, colgroup, command, content, data, datalist, dd, del, details, dfn, dialog, dir, div, dl, dt, element, em, embed, fieldset, figcaption, figure, font, footer, form, frame, frameset, h1, h2, h3, h4, h5, h6, header, hgroup, hr, i, img, input, ins, isindex, kbd, keygen, label, legend, li, listing, main, map, mark, marquee, menu, menuitem, meter, nav, noembed, noscript, object, ol, optgroup, option, output, p, param, plaintext, pre, progress, q, rp, rt, rtc, ruby, s, samp, script, section, select, shadow, small, source, spacer, span, strike, strong, sub, summary, sup, table, tbody, td, template, tfoot, th, thead, time, tr, track, tt, u, ul, var, video, wbr, xmp
Attributes are passed through verbatim and not checked.
Table of contents
The Table of Contents plugin introduces one new tag:
The table of contents takes the top level of its hierarchy from your config file. See Defining table of contents structure with
file_hierarchy for details.
The titles and intra-document structure are taken from the heading nodes.
The output looks like this:
You can optionally customize the text of the title ("Table of Contents") by adding content to the tag:
You can call out a note or a warning using—wait for it—
no-prefix=true to omit the automatic first line of bold text.
This is a multi-paragraph note with a custom first line.
Linking to sections
You can define a "heading alias" like this:
You can then link to the section like this:
This will automatically include the heading's contents and link to it:
Check out the Configuring Foobar section.
You can set custom link text by just using the non-self-closing version:
Check out the Configuration section.
Computer Words supports including documentation from symbol files. These can be generated for Python 3.5 like this:
Then tell Computer Words where to find the symbol file in your config like this:
(Remember, all paths in the config file are relative to the config file's directory.)
Now you can use the
<autodoc-python /> tag to include source docs in your Markdown files:
function: path to the symbol to be included
True, also show definitions and docstrings of all classes and functions in the module
True(default), show the fully qualified path for the symbol (e.g.
computerwords.plugin.CWPluginrather than just
CWPlugin). Children, if included, will be rendered with this value as
heading-level: If you don't want the module's name to be a top-level heading, set this to 2 to use
h2, 3 to use
Including individual classes and functions
Convenient linking to symbols
Why the intermediate JSON step?
Because the general interface with source parsers needs to work for languages besides Python. Languages tend to have parsers for themselves in their standard libraries; Computer Words should make use of them.