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.
Related
For example, when the goal is to represent several lines of a program's source code, then the AsciiDoc block markup choices are using
a literal block (....), which is converted to the literallayout DocBook tag
a listing block (----), which is converted to the screen DocBook tag
These are solid defaults, but the proper semantic markup would be programlisting in this case.
Using passthrough blocks is one solution, but at the cost of polymorphism (or convenience, if I decide to pepper my documents with ifdefs / ifndefs):
WARNING
Using passthroughs to pass content (without substitutions) can couple your content to a specific output format, such as HTML. In these cases, you should use conditional preprocessor directives to route passthrough content for different output formats based on the current backend.
I don't mind using the conditionals, but simply wondering if I am missing something obvious or straightforward? Such as passing semantic tag names to a block attrlist or something. Read through the entire AsciiDoc manual, the asciidoctor man page, the Generate DocBook from AsciiDoc article, and tried keyword searches, but couldn't find a thing. (It is highly probably though that I missed it..:)
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.
I am using Spring RestDoc together with AsciiDoc to describe my rest api. RestDoc generates different files depending if there are request parameters described / response fields etc. I would like to have one template conditionally including whatever file exists.
something like this:
Request:
include::{reqresPath}/http-request.adoc[]
Response:
include::{reqresPath}/http-response.adoc[]
Parameters:
ifeval::[{{reqresPath}/request-parameters.adoc}.exists]
include::{reqresPath}/request-parameters.adoc[]
endif::[]
ifeval::[{{reqresPath}/request-parameters.adoc}.exists]
include::{reqresPath}/request-parameters.adoc[]
endif::[]
or at least exclude warnings in case of a missing file. But I could not figure out how to suppress these.
As of today, where is no operator for ifeval available, which can be used to check the existence of a file.
The way I would go is to write an extension for Asciidoctor, which can also be done by using Java. If your projects is big enough, I would suggest to go for this solution.
The most extreme way is to make a custom TemplatedSnippet which is generating an empty snippet to be included...
I hope there is a better way to do this.
Edit:
Take a look of http://asciidoctor.org/docs/user-manual/#by-tagged-regions
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