apnadkarni/ruff

Documentation generator for Tcl

ruff's Issues

Do not generate Description section if identical to summary

Operators

Hello @apnadkarni ,
I created several methods operators like this :
method * {args} {}
method + {args} {}
It works with this operators "\ -" but not with above operators.
Is there any workaround ?
Regards

Add an option for dense formatting

Basically leave out the headers in procedural descriptions. A hack way to do this would be through CSS selectors for h3/h4! But "See also" etc. would need to change.

Markdown output has an extraneous <div yui> line at top.

Navigation pane - methods should be sorted case-insensitive or dictionary mode

Support vuepress output.

apnsimple suggestions

Reminder for rfes - see apnsimple suggestions at https://wiki.tcl-lang.org/page/Ruff%21

Expose -stylesheets option

OO constructor synopsis only shows "create" syntax, not "new"

Angle brackets not getting escaped in See also section

For <clone> in daft appears as a HTML tag.

Add link to top page to navigation pane in multipage format.

Add Top link to headings

Add navigation links to right of headers similar to those for classes and procs.

-includeprivate lists built-ins <cloned>, eval, variable etc. oo::object methods

These methods should not be listed in the method table for each class.

Links section headings need a link to top of page, maybe arrows

In multipage output from a class method heading you can navigate to the class and the Main page but not to the top of the current page. May be use two forms of up arrows to indicate top of page and Main content.

In split page mode, links to methods from navigation pane do not work

Note links in the class method summary section work fine.

Links to sections with label text do not work

Links of the form

[link text](Section title)

which should show create a link displaying "link text" linking to the section "Section title" do not seem to be recognized.

-includesource not working in 1.0b1

Support for 8.7 TclOO features (private methods etc.)

Option for namespace menu items to be unsorted

CAWT for example would like all Office menu links to appear together.

Wide procedure names intrude from navigation pane into main documentation

Add support for additional output formats

Additional output formats:

• asciidoctor output
• doctools output
• vuepress output
• latex output
• pandoc markdown output
• markdeep output

Generate an index page when outputting multiple pages

In multiple page output format, an index across all pages would be useful

Remove :: prefix in navigation pane links

Add a search/index feature like tcl-docs

HTML formatter hardcodes markup

HTML formatter hard codes markup when it should use the markdown wrappers. In a similar vein, get rid of _const, _cmd or have them use markdown markup instead.

References to sections do not seem to work.

[::ns::Section Heading] links are recognized but not resolved.

Document method forwards

At the very least, just document the name and where it forwards to.

Markdown formatter support

Add support for markdown output style

Localization

What a nice package! I need it in German, so I added localization to the package. I added a -locale option to the ::ruff::document command and added a minimal set of German localizations (for procedures only). I have put the translated strings into ruff.tcl, you may want to have them in a separate file for convenience.

Would be nice to have such thing included into the next official release.

ruff-localization.zip

Support markdeep output

Add option to change location and width of navigation pane

Provide the option to keep navigation pane in fixed position while scrolling

OO class constructor - create syntax is wrong

Main page in multipage output is missing title.

Document metaclasses

From RZ on the wiki:

Currently only oo::class classes and no metaclasses are recognized in
proc ruff::private::extract_procs_and_classes because of line :

set class_names [[info class instances ::oo::class $pattern]]

May be add an option -metaclasses and do an "[[info class instances $metclass ..]]".

Refactor option processing

Some options are read from passed arguments, others from [program_option]. Make this consistent and sane.

HTML tags with attribute values of empty string are escaped

Reported by Alex that tags were being escaped.

Turns out the problem is with any tag with an empty attribute. So

    <img src="https://aplsimple.github.io/en/tcl/hl_tcl/files/hltcl1.png" alt="x">

is correctly shown but

    <img src='https://aplsimple.github.io/en/tcl/hl_tcl/files/hltcl1.png" alt="">

is (wrongly) escaped.

Incorrect link in class method table

If a class has a inherited method that has the same name as some proc, the class method table in docs links to the proc instead of the inherited method. The method table generation should check that the name refers to a method and not just some proc higher in the hierarchy.

Sample of the problem is the register_plugin method for the class daft::behavior::Server.

Surround optional arguments with ? in synopsis

Also, the (optional, default ..) appears after the closing period which looks awkward. Maybe put it in the front instead)

Link to CSS style files instead of embedding

Options listed in random order

Optional parameters are displayed in random order, neither sorted not the original documented order in source file.

Move ruff built-in style to a separate file and include it

Add support for per-namespace options

Show links to other pages in navigation pane in multipage output

Links from methods called "<" and ">" from class method table do not work

The table links them using < etc. The name in the method element is <

See sample::base class docs

Links to sections and commands but text other than the section or command name

Undocumented mixins and superclass docs should be merged into documented classes

If C inherits or mixes in from X, and X is not being documented, inherited/mixed in methods should be documented as within C.

Replace -singlepage option with -pagesplit option

-pagesplit none|namespace

Will allow for future expansion.

Support for code blocks

Support ``` delimited code blocks.

Add support for markdown headers

Support for == markdown headers, at least in docstrings.