dev@api@doc

API Documentation Tools

G: api documentation generator git markdown

• Gatsby: https://www.gatsbyjs.org/ (JS)
  • gate template: https://github.com/sarasate/gate (JS)
    • https://gatejs.netlify.com/
• Slate: https://github.com/lord/slate (JS)
  • https://lord.github.io/slate/#introduction
  • Versioning: https://github.com/lord/slate/issues/479, https://github.com/lord/slate/issues/138 --> Open Issue :(
    • Example (with hacky versioning): http://lfex.github.io/lhc/current/
• Stripe: https://stripe.com/docs/api?lang=dotnet (inspiration...)
• Read the Docs (Python, JS: https://github.com/rtfd/readthedocs.org)
  • Supports Sphinx, rST, Git...
• https://github.com/myles/awesome-static-generators#documentation
  • DocPad: https://docpad.org/ (JS, Coffee) -> Too generalist...
  • Docsify: https://docsify.js.org/#/ (JS)
    • Awesome Docsify: https://github.com/docsifyjs/awesome-docsify
    • Versioning? Multi-language?
  • Docusaurus: https://docusaurus.io/, https://github.com/facebook/docusaurus (JS)
    • Multi-Language: OK (https://docusaurus.io/docs/en/doc-markdown#language-specific-code-tabs)
    • Versioning: OK (https://docusaurus.io/docs/en/versioning)
• Docbox: https://github.com/tmcw/docbox (JS)
  • Exemple: http://project-osrm.org/docs/v5.10.0/api/#general-options
• https://docute.org/guide/customization
• http://www.sphinx-doc.org/en/master/
• https://www.mkdocs.org/
• https://metalsmith.io/
• https://apiblueprint.org/
• https://dotnet.github.io/docfx/

G: markdown diagram

• https://support.typora.io/Draw-Diagrams-With-Markdown/ // Editor beta
  • https://bramp.github.io/js-sequence-diagrams/
  • http://flowchart.js.org/
• Mermaid: https://mermaidjs.github.io/
  • Markdown Plus - Markdown editor with extra features
  • gitbook-plugin
    • https://github.com/GitbookIO/gitbook
    • https://legacy.gitbook.com/editor
  • Confluence plugin
  • Using mermaid via docpad
  • Using mermaid in Jekyll
  • Using mermaid via Octopress
  • Using mermaid via Gatsby
    • https://www.gatsbyjs.org/
  • Mardown editor Haroopad // Editor beta
  • Sphinx extension // Python
  • Pandoc filter
    • https://pandoc.org/
  • hads
  • Mermaid Preview for VS Code // Editor
  • Package for Sublime Text 3 // Editor

Asciidoc

• http://www.cirosantilli.com/markdown-style-guide/#use-asciidoc
• Diagramming:
  • https://asciidoctor.org/docs/asciidoctor-diagram/
• Antora: https://antora.org/ (JS)
  • Showcase: https://docs.antora.org/antora/2.0/install/install-antora/
  • Insert an image: https://docs.antora.org/antora/2.0/asciidoc/insert-image/
  • Link with Asciidoctor extensions:
    • https://gitlab.com/antora/antora-asciidoctor-extensions
    • https://gitlab.com/antora/antora/issues/138
    • https://github.com/markushedvall/plantuml-encoder
    • https://medium.com/@yfuruyama/real-world-plantuml-7365ffc1b6e6
    • http://plantuml.com/
    • https://github.com/asciidoctor/asciidoctor-diagram/issues/183
    • https://puravida-software.gitlab.io/asciidiagram/
    • https://gitlab.com/puravida-software/asciidiagram
• AsciiBinder http://asciibinder.org/ (Ruby / JRuby)
  • Superseeded by Antora
• Example of a huge adoc: https://github.com/cirosantilli/linux-kernel-module-cheat/blob/v3.0/README.adoc
• Asciidoc doc: http://www.methods.co.nz/asciidoc/userguide.html

Misc

• Markdown Lorem Ipsum: https://jaspervdj.be/lorem-markdownum/
• Syntax: https://daringfireball.net/projects/markdown/syntax

---

Inspiration:

• https://www.staticgen.com/
  • https://github.com/lord/slate/wiki/Slate-in-the-Wild
  • https://docs.dwolla.com/#create-a-document-for-a-customer
  • https://github.com/pnerger/dpSlate
  • https://github.com/X1011/git-directory-deploy
  • https://github.com/dojo/dapi/wiki
  • https://dojotoolkit.org/api/
  • https://github.com/facebook/Docusaurus/issues/789
  • https://facebook.github.io/react-native/docs/getting-started
  • https://bucklescript.github.io/docs/en/interop-overview
    • https://github.com/BuckleScript/bucklescript.github.io
  • https://segment.com/blog/building-technical-documentation-with-metalsmith/

---

Tests:

• Docbox
  • multi-lang: ok
  • automatic layout from file-system: doable, but work to do...
  • versions: ?
• Docusaurus - adaptation of https://github.com/BuckleScript/bucklescript.github.io
  • multi-lang: tweaked website\static\css\custom.css, website\static\js\toggleSyntaxButton.js
• Docusaurus - new site from scratch
• Metalsmith
  • Added https://github.com/mayo/metalsmith-serve
  • Added https://www.npmjs.com/package/metalsmith-watch
  • bof...