I have to use a Asciidoc+a2x solution to generate HTML manuals out of the Asciidoc templates. Is there any opportunity to implement a full-text search into the existing solution (without migrating to an alternative like Sphinx)
Related
I need to write and build easy maintainable, goodlooking, esay to change documentation in pdf and html 5 format. The source format must be easy to edit. This maven plugin has to support my company organziation theam(fonts, colors, pictures etc.), TOC generation, separation of chapters in different files, integration of images files, easy way to put code snipets in the documentation. I have Maven build and I was wondering what is the current best descision to do that?
I was investigate two options:
Doxia - using md(markdown) as input format. There is WSWG md free
editor, support a lot of the aforemention stuffs, etc. Need external repo for its artifacts.
Asciidoctor - use asdcii doc as input format. Support templating using fragments etc.
What are the advantages and disadvantaes of using this plugins?
Are there any other good solutions?
From my attempts to build the documentation first with Doxia and then with AsciiDoc I realised that Asciidoc is the better. It allows
Easy styling using yaml files. Default styling is also very good.
Asciidoc as a mark-up language is very good documented: Uder Guide AsciiDoc
Has good online editors and the language is more powerful than markdown for example, and easier to write in comparison to the xml format.
Good examples when using with Maven and ascii doc and easy to understand configurations.
Ruby has a few good document generators like Yard, rDoc, even Glyph. The thing is that Sphinx does websites, PDF's, epub, LaTex...etc. It does all these things in restructuredtext.
Is there an alternative to this in the Ruby world? Maybe a combination of programs? If I could use Markdown as well that would be even better.
Since version 1.0, Sphinx has had a concept of "domains" which are ways of marking up code entities (like method calls, objects, functions, whatever) from lannguages other than Python and/or C.
There is a ruby domain, so you could just use Sphinx itself. The only thing you would be missing (I think) is Sphinx's ability to create documentation from source automatically using the autodoc extension, which works specifically on Python code.
If you want to use Markdown, you might check out JDoc, which is a very simple, Ruby-based documentation framework that lets you use widely-supported markup and put it under source control. It lets you edit the documentation in your text editor of choice, and it supports:
Markdown or Textile
syntax highlighting
easy internal links
a hierarchical documentation structure (useful for large projects)
customizable styling and structure (but it looks nice out of the box, too)
It generates static HTML, so the resulting documentation is easy to host and doesn't have much of an impact on your server load.
To see it in action, check out wpmvc.org.
Another couple of options would be to use Middleman which is a static site generator that accepts either Kramdown or Markdown as input.
There are also frameworks that are designed specifically for technical documentation that use Middleman (both of which are on GitHub) including lord/slate and pnerger/dpslate (the later is a fork of the former and provides some enhancements that were not appropriate for pulling). The Slate format provides a format for documentation that includes many of the features of Sphinx with some additional enhancements. It features a three-pane view of a document which includes an automatically generated Table of Contents, a Main center body, and then sample code panel to the right. Like Sphinx the sample code has syntax highlighting.
I know it is possible to write my maven site in markdown, using e.g.
http://code.google.com/p/doxia-module-markdown/wiki/Usage
Is it also possible to create books written in markdown or rest? I couldn't make this work using book-descriptors as described in
http://maven.apache.org/doxia/book/index.html
How do I tell doxia in which markup language my sections are written?
You can generate book from markdown using pandoc
Doxia is a small tool which covers to generate simple html only
But you should be able to generate maven site and books using same markdown.
I'm looking to create PDF files instantly online given user input in my html/php page.
are there any FREE API's out there that will allow me to do this?
various options, here are a couple:
Prince XML
wkhtmltopdf
TCPDF
HTML2PDF
PDF converter
PDFSharp
pdflib
formatter coverters
Php uses the PDFlib library, it has a lot of pdf functions, check it out here http://php.net/manual/en/book.pdf.php
You could probably use pdflib
Hi You have two or three approaches:
1) If you can work with XML, that is, the source of your PDF file is in XML format, you could use XSL and XSL:Fo to generate the PDF. XSL and Fo are declarative languages so you can control the PDF layout external to your application. Fo creates only documents, not interactive forms.
2) If you can work in Java, you could use iText to generate the PDF using a jar/api. There is also iTextSharp for C#. Using iText, you can also create PDF Forms, not just documents.
3) If you have XHTML and just want to create PDFs that look like your HTML pages, there are several options - just search the web for HTML to PDF converters.
If your pdf isn't overly complex, you should look into XFDF before making an architectural decision. The main benefit to this approach is that there is no need to store pdf's in the db or on hard drive. Additionally, I have seen many pdf generation implementations that use home grown batch processes that are buggy and only create another 'moving part' in an application. If you have very complex pdf needs and don't mind the overhead of storing the pdfs, pdflib is a good choice.
Is it possible to generate a set of wiki pages from XML comment file generated by Visual Studio?
I'm talking about something like Sandcastle, but for wiki format instead of compiled CHM.
Edit: I'm using MediaWiki which can import/export articles in XML. So I hope that it is possible to write a transformation converting XML comments to MediaWiki XML.
I'd recommend a bit different solution:
Use Help Server to publish .CHM/.HxS on the web
Use special MediaWiki templates to link reference from Wiki like here.
Use <see href="..."> to link Wiki pages from XML comments
See also: FiXml
This is not exactly what you wanted, but I hope this will be helpful.
If the items mentioned above do not suffice, have you tried to simply build your own XSLT transform into the wiki markup of your choice?
You can write a simple application in .NET (or pick your platform of choice) to transform the doc XML format to wiki XML format. You'd still have to keep the wiki updated with the output files manually.