opensuse / rng2doc Goto Github PK
View Code? Open in Web Editor NEWConverts a RELAX NG schema into documentation
License: MIT License
Converts a RELAX NG schema into documentation
License: MIT License
filler issue created by bitbucket_issue_migration
filler issue created by bitbucket_issue_migration
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.
In rng.py the relax.rng
is downloaded to validate the schema. IMHO, this can be dangerous, because:
If possible, it would be safer to include the relax.rng
file.
The output contains some German text (like "Vaterelement"). This should be English.
Adapt the user documentation to the last changes.
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.
When using xsl:message
inside a XSLT stylesheet, the messages don't appear.
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.
Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)
The user starts the script and passes a RELAX NG schema.
The script extracts the information of the schema and output for each element:
a:documentation
elementfiller issue created by bitbucket_issue_migration
In most modules there is this line:
import logging
# ...
LOG = logging.getLogger(__name__)
However, we have already a logging module: rng2doc/log.py.
Use the "right" logging module. 😉
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.
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?
--style STYLE
which allows to choose between tdg
and svg
The tree has to be "clean": "flat", no double entries etc.
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:
version
attribute in its root element; this way, we can identify any compatibility issues<namespace/>
element be optional?<description>
element be optional?<description>
element? Maybe as <description xml:lang="en">
?id
attribute in <element>
be xml:id
?The XSLT for transforming the intermediate format to HTML has two template rules which are too long.
The readability should be increased in splitting these templates in several sub templates.
The graphical can be simplified. Descendant or sibling nodes of the same type can be merged.
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.
All the symbols of the graphical view should be explained in a legend near the graphical view.
Currently, rng2doc allows to output XML and HTML. However, some other projects like KIWI would love to see an output in RST.
Maybe write a XSLT stylesheet or an additional Python module inside rng2doc to drive this transformation.
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.
--output
to contain a directory name when choosing --output-format=html
filler issue created by bitbucket_issue_migration
Please see title.
Use pytest-xmlcomp for testing.
The overflow-property of the section should be set to scroll or something like that.
Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)
A user wants a general format to adapt the output of the script
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.
Add an option --format
to choose from different output formats.
There are two options to tackle this:
It should be possible for the user to interact with the graphical view of each RELAX NG element
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.
filler issue created by bitbucket_issue_migration
filler issue created by bitbucket_issue_migration
A manpage is missing. We should write one.
Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)
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.
Offer another option/parameter that the user can set/enable that operates in "chunking mode".
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.
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:
rng2doc
command line parameter, e.g. `--title 'My fantastically Relax NG vacation schema'<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.
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 named patterns of RELAX NG schema should be visualized as pydot-cluster.
filler issue created by bitbucket_issue_migration
In example the DocBook schema has four different "info" elements:
The offical documentation of DocBook adds also the name of the define because this name must be unique. Do the same thingie in rng2doc
filler issue created by bitbucket_issue_migration
Originally reported by Thomas Schraitle (Bitbucket: tomschr, GitHub: tomschr)
A user wants to output a RNG schema as HTML.
Output the documentation as HTML.
Check if the following is appropriate:
Related to #3
The transform algorithm is really, really slow. Find a way to increase the performance of the algorithm.
see heading
filler issue created by bitbucket_issue_migration
Create some test cases for XSLT.
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
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.
Add a row for the default value to each attribute table.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.