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.
Related
I have lot of documentation written in AsciiDoc and correctly separated into folders. I use asciidoctor with a custom CSS to render my docs to HTML. The problem with this is that it generates a single HTML page that is very long. I was surfing the web and found that the atom docs are also written in AsciiDoc, but these docs have not all the information together, in fact they are separated into different sections.
Here the atom docs: https://atom.io/docs/v0.201.0/getting-started-why-atom
I want to know if there is a tool that can generate this, a flag or a specific syntax.
I think it is not really user friendly to have all the info in one long single page.
I have a site where the static content is generated using the asciidoctor-jekyll plugin and jekyll.
I had also plugged the java version of asciidoctor to generate views with the play framework at some point but decided that I prefer that the content I generate with asciidoctor to be static and delivered by a CDN.
EDIT:
Also, GitBookIO supports asciidoctor.
I saw this related question about publishing toolchain but I know many people did lot of work to produce publishing toolchains recently.
One great example I found is this project from akosma.
Avdi Grimm shared his work with org-mode in this project
I know there are (should be) many others.
What I'm looking for, is a publishing toolchain with
asciidoc / markdown / textile / org-mode or latex input. I don't want xml input
pdf AND html output, epub output is not a requirement for me.
What I can
author templates in latex / html / css / js. again, no xml.
read and write ruby and shell scripts
Take a look at asciidoc, this is what O'Reilly has started using and it is a refreshing break from DocBook. I use asciidoc, the tools and support leaves a little to be desired, but there are people working to create better alternatives (that don't involve Python and the existing Docbook pipeline).
Check out this: https://github.com/runemadsen/asciidoc
EDIT 1/6/13: You also really need to check out AsciiDoctor. Dan Allen from RedHat has been spending a lot of time on this particular package and Ryan Waldron. I expect great things from AsciiDoctor as it is starting to emerge as a foundation for a bunch of important AsciiDoc documentation efforts.
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.
There are many libraries for transforming markups like reStructuredText and markdown to HTML. I have some users who are familiar with the markup used in Atlassian's Confluence wiki product, which is unfortunately proprietary -- is there any open source compiler for the confluence wiki markup format, or possibly something that would transform it to an intermediate format?
I think Confluence uses the Textile markup format. I have used over the last few years a rails application that used the gem RedCloth to do the transformation, and I could switch between the 2 formats. I never checked if it is complete interchangeable, however.
You could check for yourself if it is sufficient at Try RedCloth.
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.