README.md

Nyandoc: scaladoc/javadoc HTML parser / document generator

日本語の解説を書きました

tl;dr

• This software can convert javadoc/scaladoc html to markdown format.
• Text-editor friendly!
• Under development, but basically works.

Pre-build documents

• Scala API documentation(scala-library): http://todesking.github.io/nyandoc/scala-docs-markdown-2.11.5.zip

About

Goal: To parse javadoc/scaladoc HTML and generate the document with specific format.

Motivation: I need Scala API documentation with more text-editor friendly format than HTML. But Scaladoc only support to generate HTML. "doclet" feature is provided, but it is very restricted and difficult to understand. So I don't generate document from sources directly, but instead parse HTML and transform it.

Current status

• Basic features are supported
  • Parse scaladoc to internal representation
  • Parse javadoc to internal representation
  • Generate markdown documents from internal representation
• Not supported yet
  • Other output format
  • Old-format(Java 1.6 or older) javadoc html
  • Some html tags (ol, blockquote, table, image)
  • Text layout engine is not support for fullwidth characters.

Install

The project is packaged with Conscript.

Install conscript first, and

$ cs install todesking/nyandoc

Usage

Currently, output format fixed to markdown.

$ nyandoc <source-location> <dest-dir>

or

$ sbt 'run <source-location> <dest-dir>

source-location could be directory, html, jar, or zip. File type is determined by its extension.

Links

• Scala API Documentation
  • 2.11.5
• JDK API Documentation
  • JDK8
  • JDK7
  • Japanese document(1.4 - 8)
• Java/Scala library documentation
  • Jar-packed documents often found in maven.org

Example usage: Use ctags to generate tags file

Add ~/.ctags to this:

--langdef=markdown-scala-nyandoc
--regex-markdown-scala-nyandoc=/^#+ .*(def|val|var|type)[[:space:]]+([^ (\[]+)/\2/

--langdef=markdown-java-nyandoc
--regex-markdown-java-nyandoc=/^#+ .*[[:space:]]([a-zA-Z0-9]+(<.+>)?)\(/\1/

and

ctags --langmap=markdown-scala-nyandoc:.md -R . # For Scala project
ctags --langmap=markdown-java-nyandoc:.md -R .  # For Java project

in nyandoc document directory.

Example usage: Use Vim as document browser

I used these technologies:

• Vim - THE text editor
• unite.vim - Multi-purpose "filter and select" plugin like ctrlp.vim or anything.el.
• unite-outline - Gather outline information from various file types for unite.vim.

At first,

:Unite file:.nyandoc/ -default-action=rec

and select scala-2.11.2

and select immutable/Seq.md

and

:Unite outline