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.
Related
There are lot of Swagger related codegens to convert a YAML to HTML file , but is there an eclipse plugin available which can open or convert a YAML to HTML ?
I have searched in multiple places but there's no place where we can find such a plugin .Plugins like Yedit help seeing a YAML in colour syntax form but not as a HTML ?
You might want to take a look at RepreZen API Studio, available as a standalone desktop application or as an Eclipse plugin.
It includes swagger-codegen and other open source generators, which can create various forms of HTML documentation from your YAML-formatted Swagger-OpenAPI spec. Code generation is fully integrated into the IDE, but can also be run from the command line or CI/CD automated builds.
To clarify, there's no HTML "equivalent" of a Swagger-OpenAPI spec, or any other form of YAML. So it's not a simple matter of converting one file format to another. But there are various components that render a machine-readable OpenAPI spec, in YAML or JSON form, in a user-friendly HTML documentation format, often with integrated sandbox testing.
One of these is Swagger-UI, and it's included in the HTML formats that are supported by RepreZen API Studio. I hope that helps.
I'm using a slightly modified version of the example generator from Jekyll's plugins section of their docs (https://github.com/mojombo/jekyll/wiki/Plugins#generators) and I'm curious if there is any way to parse a liquid/markdown file instead of a plain HTML files from the example?
Notice this line:
self.read_yaml(File.join(base, '_layouts'), 'category_index.html')
That category index.html file is the target file which will be used in generated files. My goal is to be able to pass an object to a my generator from my _config file which I can then use to build a bunch of pages from a .markdown file instead. Does anyone know if this is possible or have any recommendations for achieving this? I looked into the Kramdown lib that's used to parse markdown internally, and I'm not opposed to invoking it myself if I have to, just wasn't sure if I was going deeper than I needed to for something that should be so simple. The API for the Page object which my generator creates is here: http://ruby-doc.org/gems/docs/j/jekyll-0.12.0/Jekyll/Page.html
Thanks a ton,
- Keith
You can generate virtually any format you want, from virtually any data source you want, in a generator, because you're writing straight Ruby with full access to the Jekyll object model. For example, here's a generator I put together the other night that fetches GitHub commits during jekyll build.
The question I would be asking is this:
Do I need a plugin to accomplish this?
If so, do I need a formal generator plugin as discussed in the Jekyll docs?
Or should I subclass, monkey-patch, or otherwise change the behavior of the built-in generator?
Also, the differences between Markdown and HTML files in this context (where you control 100% of what gets generated) are mostly nominal. read_yaml IIRC will actually read the front matter from both, so that shouldn't be an issue.
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'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.
Anyone know of a wiki or wiki plugin that generates a PDF file or CHM file that spans the entire wiki?
I would like to have control of the table of contents.
I would like the internal and external links to work.
Ideally allow for tweaking the output template, but that is not a deal-breaker.
I want to generate content using WIKI syntax and mindset (lots of cross-links etc), but ship the content in PDF, CHM or an embedded application form. Something friendlier than installing the wiki software on the enduser machine...
XWiki does this out of the box.
The MediaWiki PDF Export extension allows you to select a group of PDF pages. I've not installed it yet, so unsure if it's easy to use that feature to select all the pages.
Confluence lets you choose pages when you export to PDF a space
But you can't customise a lot the PDF
You can customise it slightly through a theme (based on velocity)
Sphinx (https://www.sphinx-doc.org) is a fairly nice tool for generating HTML (or CHM) and PDF documentation, with wiki-like syntax. It is not a wiki; you can't edit through the web and generating HTML requires a build process. Still, it is pretty nice, with cross-references, fairly simple markup, and (in the HTML output) a search engine implemented in JavaScript with no server-side dependencies beyond static file hosting. Sphinx was developed for the new version of the Python documentation and is pretty themable; for example, the GeoServer project (which I work on, excuse the shameless plug) is using Sphinx with a custom theme for the new version of their user and developer manuals.
JIRA (http://www.atlassian.com/software/jira/default.jsp) is your geeky wet dream in terms of control; it exports to PDF (amongst other) and you can have complete control of pages, TOC and other aspects, although expect some complexity to set it up.
Microsoft has an HtmlHelp Authoring tool that can create chm files from html files.
If you need the help files both on the web and within deployed applications, generating the help from the same files used on the web could be a great solution. If the help site was created using asp.net (ie database driven) it might be worth using basic styles and creating a tool to generate html files by reading in the served out pages?
Have a look at: http://msdn.microsoft.com/en-us/library/ms524239(VS.85).aspx
I guess one could also additionally then create a PDF from the Html pages?