I'd like to include some phpdoc-generated documentation into my already existing docbook documentation.
My idea was to let phpdoc generate the documentation in the docbook-format and then import parts (based on packages and subpackages) of it using XInclude. I'm using Docbook 5 for my documentation. Is there any way to achieve this?
What I tried this far is generating a docbook using XML:DocBook/peardoc2:default as phpdoc parameter.
PHPDocumentor's docbook is divided into several files - thats great, but the files look something like this
<chapter id="package.default">
<title>default</title>
&package.default.default;
&package.default.foobar;
</chapter>
As far as I understand those are external entities, but they need to be referenced in a DTD - making them useless for my effort, as there is no DTD generated by phpdoc and I don't want to include a file for every class and method by hand.
First, if this is really supposed to be docbook 5, you need "xml" before "id" like this:
<chapter xml:id="package.default">
Second, you could use an XML Catalog to hold all your entity references: http://www.sagehill.net/docbookxsl/Catalogs.html
Related
I'm rather new to Sphinx and ReST and I've "inherited" a big project.
The documentation consists of hundreds of pages with how to's, etc. There are several files (one for each class) where the respective functions are described using the ".. py:function::" directive.
So each of these pages is basically like this:
Some description text explaining the class
py:function:: class.myFunction(param1, param2)
parameter description
code example, ...
py:function:: class.myFunction2
parameter description
code example, ...
Now, I'd like to list all functions of all different pages in one single XML file, if possible grouped by their class, but without the descriptions and examples. Is this possible with some built-in Sphinx parser or do I have to write my own? Or is there any other directive or config option that may be helpful?
The XML file should be like this:
<class1>
<function1>
<param1>
<param2>
...
<function2>
...
<class2>
<function1>
...
I found ViewLists and the Parsing directive in the Sphinx documentation but i'm not sure how to correctly use them and if that's the solution to my problem.
I have a couple of examples (all with titles) and I'd like to create an index/list out of them automatically.
An example can be seen in the chunked AsciiDoc User Guide table of contents (or beneath):
The asciidoc source of the AsciiDoc User Guide does not show anything specific to me for Asciidoc itself, I could find the following hint to Docbook:
DocBook toolchains will normally automatically number examples and generate a 'List of Examples' backmatter section.
I'm looking for the (asciidoctor?) standard html5 rendering, but I'm open for different suggestions.
Adding the :doctype: book attribute alone does not do it. So I merely hit dead ends not knowing if it is possible at all. Also I'm new to Asciidoc so I might just miss some pointers, too.
The Python Asciidoc repo includes the a2x tool, which is a wrapper around a DocBook toolchain. It is DocBook that is producing these entries in the table of contents. Neither Python Asciidoc, nor asciidoctor, can do this out of the box.
You would need to curate the lists manually, or create a macro that does the curation for you. This thread might prove helpful: https://github.com/asciidoctor/asciidoctor-extensions-lab/issues/111
I'm using a Sphinx extension (this one) which generates some ReST markup dynamically. Sphinx uses that ReST to generate html documentation.
I want to examine and run doctests on the generated ReST markup. Normally I use
sphinx-build -E -b html docs dist/docs
to generate the html output, but there is no rst "builder" equivalent to the html one.
How can I examine the generated ReST markup?
Use the Sphinx extension sphinx.ext.doctest, following its syntax and markup.
Then run make doctest to run the doctests.
Update
In response to your comments and taking the suggestion from #mzjn, it sounds like you want to generate an intermediate set of documentation that is in reStructuredText. The Sphinx extension restbuilder might be want you seek.
From that point, make doctest might be want you want.
Is there any quick way to output printable documentation using phpDocumentor 2?
Option -o doesn't work...
One possible way would be to create a custom template (based on XSLT or Twig) that transforms the compiled class info into printable HTML. Have a look at the existing templates in the PHPDocumentor 2 repositories to get an idea what a template looks like. You can cut out much of the unneeded navigation stuff.
I'm trying to use the Export feature of OpenOffice Writer to create an XHtml File from an ODT containing an XForm.
What I noticed was that the XForm Model was not getting exported. I copied the default XSL file used and I changed the "xsl:stylesheet" node's "exclude-result-prefixes" to an empty string.
The output was the same. I searched the internet for more help and came across
https://issues.apache.org/ooo/show_bug.cgi?id=87731
The "xsl:template" tags provided here helped in exporting the most of the content.
1. The XForm instance, model, binding etc.
However the actual controls were still missing...
I believe the trick lies in "xsl:template" tags, but have no documentation to understand how the export feature uses them.
Any ideas on this?????
Decide which XHTML element maps to each missing XForms control, then create a xsl:template matching each control which includes the desired XHTML output. Here are a few examples of similar conversion stylesheets:
Atom2HTML
RDF2HTML(View Source)
XML2XHTML
XSLTForms is an excellent reference as well.