The graphical can be simplified. Descendant or sibling nodes of the same type can be merged.

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

Use the keywords :param:, :return: etc. in the docstring of a function.

For more information, see http://www.sphinx-doc.org/en/stable/domains.html#info-field-lists

filler issue created by bitbucket_issue_migration

The list of attributes can be really long. For finding the right attribute quickly there should be a TOC area in front of it with links to all the attributes.

It should be possible for the user to interact with the graphical view of each RELAX NG element

• A link to the components (element and attribute) should be available.
• Make it possible to collapse a branch of the tree
• The user can zoom in and out
• The user can easily export the graph into multiple formats like SVG, PNG, dot ...
• The user can reorganize the position of the nodes via drag and drop
• Add the annotation docstrings to the graphical view as tooltips.

filler issue created by bitbucket_issue_migration

The XSLT for transforming the intermediate format to HTML has two template rules which are too long.

• <xsl:template match="element" mode="visualize">
• <xsl:template match="attribute">

The readability should be increased in splitting these templates in several sub templates.

The named patterns of RELAX NG schema should be visualized as pydot-cluster.

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

Try to write test cases for each subject, problem, or issue.

It might be probably useful to apply this for some RNG fragments.

Use pytest

In example the DocBook schema has four different "info" elements:

• info (db.titleforbidden.info) — A wrapper for information about a component or other block without a title
• info (db.titleonly.info) — A wrapper for information about a component or other block with only a title
• info (db.titleonlyreq.info) — A wrapper for information about a component or other block with only a required title
• info (db.titlereq.info) — A wrapper for information about a component or other block with a required title

The offical documentation of DocBook adds also the name of the define because this name must be unique. Do the same thingie in rng2doc

Problem

Compare these two executions:

• Generating XML:

  $ rng2doc --output-format=xml --output=/tmp/foo.xml /tmp/foo.rng
  

• Generating HTML

  $ rng2doc --output-format=html --output=/tmp/foo.html foo.rng
  

However, for HTML, you can't just add a directory.

Solution

• allow --output to contain a directory name when choosing --output-format=html
• allow creating the directory when it doesn't exist

It would be cool if the script can perform any timing calculations. For example, when adding the --timing option, the script could output how long the whole process took.

At the moment the elements of external namespaces are not visualized. This results in dead ends inside the graphical view. Please see the attached screenshot.

It would be great if rng2doc would allow adding a custom title to pages both for the HTML <title> and for the navbar-header. I guess there could be two ways of implementing that:

1. via rng2doc command line parameter, e.g. `--title 'My fantastically Relax NG vacation schema'
2. via a special comment in the schema itself, e.g. a special <a:documentation>My fantastically Relax NG vacation schema</a:documentation> element somewhere at the top.

I'd actually prefer (2.) because that would allow making the title independent from the command line I am using and also keeps the command line shorter. I am not sure if that's possible in a reasonable way, though.

see heading

The vector graphic of the graph of an RELAX NG should be scale correctly. It should be possible to set a maximum value for the height and the width.

Adapt the user documentation to the last changes.

Add a row for the default value to each attribute table.

filler issue created by bitbucket_issue_migration

Chromium-based browsers seem to render some content atop the larger SVGs, apparently due to a fixed SVG height or something like that. Firefox renders it correctly.

@quatran said he would like to look into the issue... assigning him.

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

According to your documentation, the internal data structure looks like this:

<documentation>
  <element name="profiles">
    <namespace/>
    <description>Creates Namespace Section for Drivers</description>
    <child id="profile"/>
  </element>
  <element name="users">
    <namespace/>
    <description>A List of Users</description>
    <child id="user"/>
    <attribute>
      <name>group</name>
      <namespace/>
      <description>Contains the group to which the user belongs</description>
      <type>
        <description/>
        <param/>
      </type>
      <use>required</use>
    </attribute>
    <!-- ... -->
  </element>
  <!-- ... --->
</documentation>

Three inconsistencies:

• The name of the element is written as <element name="...">. However, the attribute name is written as <attribute><name>.
  Could this be made consistent? Such as <attribute name="...">.

• The <use> element contains probably the values "required" or "optional". Is that assumption correct? In that case, you could move this information like this:
  <attribute name="..." required="yes|no">
  By default, "no" is the default value.

• The id attribute from <child id="profile"/> refers to another element. As such, shouldn't it be named "ref" or something similar?

It could help to make XPaths a bit easier. 😁

Furthermore, it may help to formalize the structure if we would have a RELAX NG grammar. Some questions:

• The document structure should have a version attribute in its root element; this way, we can identify any compatibility issues
• Should the <namespace/> element be optional?
• Should the <description> element be optional?
• Should the natural language of some description be preserved in the <description> element? Maybe as <description xml:lang="en">?
• Should the id attribute in <element> be xml:id?

filler issue created by bitbucket_issue_migration

Create some test cases for XSLT.

filler issue created by bitbucket_issue_migration

Use pytest-xmlcomp for testing.

A manpage is missing. We should write one.

Problem

When using xsl:message inside a XSLT stylesheet, the messages don't appear.

Solution

in the openSUSE/rstxml2db we have a logging_xslt function. It uses the .error_log property.

However, each xsl:message needs to start with INFO, ERROR, WARNING etc. These are indicators for the log level and are mapped to the respective Python logging level.

filler issue created by bitbucket_issue_migration

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

The tox.ini file contains py.test, but it should be pytest.

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

Scenario

A user wants to output a RNG schema as HTML.

Tasks

Output the documentation as HTML.

Check if the following is appropriate:

• Separate the data extraction from the output generation
• Use template strings as a first start.
• If template strings aren't powerful enough, maybe you need to use the Jinja module. This would probably allow greater flexibility but comes with a cost (complexity, maintainability, dependency).

Relations

Related to #3

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

Jürgen needs to choose a license before starting the work. 😉

The overflow-property of the section should be set to scroll or something like that.

The transform algorithm is really, really slow. Find a way to increase the performance of the algorithm.

Current HTML output creates filenames like element-45.html instead of article.html.

If there are element names which have a different content model, we need to take that into account and name it accordingly.

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

Scenario

A user wants a general format to adapt the output of the script

Task

The internal Python structure could be written as a XML format. This has the benefit of creating XSLT stylesheet which are able to transform it into any format the user like.

Checklist

• Add an option --format to choose from different output formats.

• There are two options to tackle this:

  1. create your own XML structure
  2. create a simplified, condensed version as RNG schema

Problem

In rng.py the relax.rng is downloaded to validate the schema. IMHO, this can be dangerous, because:

• website can be offline
• website can change in the future (is that likely?)
• there are restrictions on the computer to connect to the Internet

Solution

If possible, it would be safer to include the relax.rng file.

filler issue created by bitbucket_issue_migration

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

Scenario

The user starts the script and passes a RELAX NG schema.

Task

The script extracts the information of the schema and output for each element:

• a title and its purpose; the purpose can be retrieved by the a:documentation element
• its content model
• its attributes
• maybe it's schema declaration
• the parent element

Examples

• For DocBook, use the TDG, for example book definition
• For TEI, the TEI element definition

Related

See #3 and #4

The transform method has still some template specific parts. It should be possible to create a new transform template like svg.py without modifying the transform method itself.

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

Problem

Currently, the script creates one, big HTML file with all the text and graphics. It would be convenient, if the user could select that each element is written into a separate HTML file.

Solution

Offer another option/parameter that the user can set/enable that operates in "chunking mode".

Problem

As suggested by @sknorr, the script could offer a second option in "TDG style". For example, the content model of the set element in The Definitive Guide looks like:

set ::=
    Sequence of:
        One of:
            Sequence of:
                Interleave of:
                    title
                    titleabbrev?
                    subtitle?
                info? (db.titleforbidden.info)
            info (db.titlereq.info)
        toc?
        One or more of:
            article
            book
            set
        setindex?

Solution

• add an additional option --style STYLE which allows to choose between tdg and svg
• choose a default

Prerequisites

The tree has to be "clean": "flat", no double entries etc.

This works:

(env) ~/data/gits/rng2doc > rng2doc -f html -o ~/data/gits/geekodoc/geekodoc/rng/r2d2 \
  ~/data/gits/geekodoc/geekodoc/rng/geekodoc5-flat.rng

This fails:

(env) ~/data/gits/geekodoc/geekodoc/rng > rng2doc -f html -o r2d2 geekodoc5-flat.rng

Traceback (most recent call last):
  File "/home/sknorr-l/data/gits/rng2doc/env/bin/rng2doc", line 33, in <module>
    sys.exit(load_entry_point('rng2doc', 'console_scripts', 'rng2doc')())
  File "/home/sknorr-l/data/gits/rng2doc/src/rng2doc/cli.py", line 123, in main
    result = parse(args['RNGFILE'])
  File "/home/sknorr-l/data/gits/rng2doc/src/rng2doc/rng.py", line 125, in parse
    relaxng_schema = etree.parse("schemas/relaxng.rng")
  File "src/lxml/etree.pyx", line 3521, in lxml.etree.parse
  File "src/lxml/parser.pxi", line 1859, in lxml.etree._parseDocument
  File "src/lxml/parser.pxi", line 1885, in lxml.etree._parseDocumentFromURL
  File "src/lxml/parser.pxi", line 1789, in lxml.etree._parseDocFromFile
  File "src/lxml/parser.pxi", line 1177, in lxml.etree._BaseParser._parseDocFromFile
  File "src/lxml/parser.pxi", line 615, in lxml.etree._ParserContext._handleParseResultDoc
  File "src/lxml/parser.pxi", line 725, in lxml.etree._handleParseResult
  File "src/lxml/parser.pxi", line 652, in lxml.etree._raiseParseError
OSError: Error reading file 'schemas/relaxng.rng': failed to load external entity "schemas/relaxng.rng"

The output contains some German text (like "Vaterelement"). This should be English.

Problem

In most modules there is this line:

import logging
# ...
LOG = logging.getLogger(__name__)

However, we have already a logging module: rng2doc/log.py.

Solution

Use the "right" logging module. 😉

Problem

Currently, rng2doc allows to output XML and HTML. However, some other projects like KIWI would love to see an output in RST.

Solution

Maybe write a XSLT stylesheet or an additional Python module inside rng2doc to drive this transformation.

filler issue created by bitbucket_issue_migration

filler issue created by bitbucket_issue_migration

All the symbols of the graphical view should be explained in a legend near the graphical view.

Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)

• move to GitHub
• connect to Travis
• add Jürgen to this project
• discuss the project with Jürgen
• define targets

Please see title.