Tag: documentation
Zeal: Open source documentation browser for Linux and Windows
Documentation at scale: The principles
explainshell.com: Visual mapping of command line arguments from Ubuntu man pages
Swagger 2.0: Open source REST API framework
From the Swagger 2.0 Github page:
The goal of Swagger™ is to define a standard, language-agnostic interface to REST APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined via Swagger, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interfaces have done for lower-level programming, Swagger removes the guesswork in calling the service.
Use cases for machine-readable API interfaces include interactive documentation, code generation for documentation, client, and server, as well as automated test cases. Swagger-enabled APIs expose JSON files that correctly adhere to the Swagger Specification, documented in this repository. These files can either be produced and served statically, or be generated dynamically from your application.
Without going into a long history of interfaces to Web Services, this is not the first attempt to do so. We can learn from CORBA, WSDL and WADL. These specifications had good intentions but were limited by proprietary vendor-specific implementations, being bound to a specific programming language, and goals which were too open-ended. In the end, they failed to gain traction.
Swagger does not require you to rewrite your existing API. It does not require binding any software to a service–the service being described may not even be yours. It does, however, require the capabilities of the service be described in the structure of the Swagger Specification. Not all services can be described by Swagger–this specification is not intended to cover every possible use-case of a REST-ful API. Swagger does not define a specific development process such as design-first or code-first. It does facilitate either technique by establishing clear interactions with a REST API.
Static documentation template for your API using Markdown with support for 50+ languages
Link: A review of all most common API editors
MkDocs: Markdown-based static site generator written in Python meant for building documentation
Sphinx: A powerful documentation creation tool written in Python that uses the reStructuredText markup language
According to the website, Sphinx…
…has excellent facilities for the documentation of Python projects, but C/C++ is already supported as well, and it is planned to add special
support for other languages as well.”
Sphinx outputs in the following formats…
HTML (including Windows HTML Help), LaTeX (for printable PDF versions), ePub, Texinfo, manual pages, plain text