Documentation: Documentation for Modern JavaScript

Documentation.js

The documentation system for modern JavaScript   

📅 Current maintenance status

  • Supports modern JavaScript: ES5, ES2017, JSX, Vue and Flow type annotations.
  • Infers parameters, types, membership, and more. Write less documentation: let the computer write it for you.
  • Integrates with GitHub to link directly from documentation to the code it refers to.
  • Customizable output: HTML, JSON, Markdown, and more

User Guide

Globally install documentation using the npm package manager:

$ npm install -g documentation

This installs a command called documentation in your path, that you can point at JSDoc-annotated source code to generate human-readable documentation. First, run documentation with the --help option for help:

Usage:

# generate markdown docs for index.js and files it references
documentation build index.js -f md

# generate html docs for all files in src, and include links to source files in github
documentation build src/** -f html --github -o docs

# document index.js, ignoring any files it requires or imports
documentation build index.js -f md --shallow

# validate JSDoc syntax in util.js
documentation lint util.js

# update the API section of README.md with docs from index.js
documentation readme index.js --section=API

# build docs for all values exported by index.js
documentation build --document-exported index.js

# build html docs for a TypeScript project
documentation build index.ts --parse-extension ts -f html -o docs

Commands:
  build [input..]   build documentation
  lint [input..]    check for common style and uniformity mistakes
  readme [input..]  inject documentation into your README.md

Options:
  --version  Show version number                                       [boolean]
  --help     Show help                                                 [boolean]

Examples

Documentation

Contributing

We have plenty of issues that we'd love help with.

  • Robust and complete JSDoc support, including typedefs.
  • Strong support for HTML and Markdown output
  • Documentation coverage, statistics, and validation

documentation is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

Download Details:

Author: Documentationjs
Source Code: https://github.com/documentationjs/documentation 
License: View license

#javascript #documentation 

Documentation: Documentation for Modern JavaScript
Nat  Grady

Nat Grady

1661165460

Pkgdown: Generate Static Html Documentation for an R Package

pkgdown  

pkgdown is designed to make it quick and easy to build a website for your package. You can see pkgdown in action at https://pkgdown.r-lib.org: this is the output of pkgdown applied to the latest version of pkgdown. Learn more in vignette("pkgdown") or ?build_site.

Installation

# Install released version from CRAN
install.packages("pkgdown")
# Install development version from GitHub
devtools::install_github("r-lib/pkgdown")

Usage

Get started with usethis:

# Run once to configure your package to use pkgdown
usethis::use_pkgdown()

Then use pkgdown to build your website:

pkgdown::build_site()

This generates a docs/ directory containing a website. Your README.md becomes the homepage, documentation in man/ generates a function reference, and vignettes will be rendered into articles/. Read vignette("pkgdown") for more details, and to learn how to deploy your site to GitHub pages.

pkgdown 2.0.0 and Bootstrap 5

pkgdown 2.0.0 includes an upgrade from Bootstrap 3 to Bootstrap 5, which is accompanied by a whole bunch of minor UI improvements. If you’ve heavily customised your site, there’s a small chance that this will break your site, so everyone needs to explicitly opt-in to the upgrade by adding the following to _pkgdown.yml:

template:
  bootstrap: 5

Then learn about the many new ways to customise your site in vignette("customise").

In the wild

At last count, pkgdown is used by over 6,000 packages. Here are a few examples created by contributors to pkgdown:

bayesplot (source): plotting functions for posterior analysis, model checking, and MCMC diagnostics.

valr (source): read and manipulate genome intervals and signals.

mkin (source): calculation routines based on the FOCUS Kinetics Report

NMF (source): a framework to perform non-negative matrix factorization (NMF).

Comparing the source and output of these sites is a great way to learn new pkgdown techniques.

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Download Details:

Author: r-lib
Source Code: https://github.com/r-lib/pkgdown 
License: Unknown, MIT licenses found

#r #documentation #tool #html 

Pkgdown: Generate Static Html Documentation for an R Package
Nat  Grady

Nat Grady

1661083980

Docthis: RStudio Addin to Create Skeleton Documentation for Functions

docthis: Document this [object]

An RStudio addin that builds the skeleton of documentation for an R function or dataframe using the roxygen2 syntax.

Installation

You will need to be running RStudio v0.99.878 or later.

devtools::install_github("mdlincoln/docthis")

Usage

Say you've written a function (let's call it lm!) but haven't put together your documentation quite yet. Load the function into the current environment, select the function tile, and call the "Document object" addin, which will paste in some skeleton roxygen2 documentation above your function definition:

#' FUNCTION TITLE
#'
#' FUNCTION DESCRIPTION
#'
#' @param formula DESCRIPTION.
#' @param data DESCRIPTION.
#' @param subset DESCRIPTION.
#' @param weights DESCRIPTION.
#' @param na.action DESCRIPTION.
#' @param method DESCRIPTION.
#' @param model DESCRIPTION.
#' @param x DESCRIPTION.
#' @param y DESCRIPTION.
#' @param qr DESCRIPTION.
#' @param singular.ok DESCRIPTION.
#' @param contrasts DESCRIPTION.
#' @param offset DESCRIPTION.
#' @param ... DESCRIPTION.
#'
#' @return RETURN DESCRIPTION
#' @examples
#' # ADD EXAMPLES HERE
lm <- function(.....

This will also work for data.frames, which you should be thoroughly documenting in R/data.R. Again, make sure the data.frame is available in the current environment, highlight its name, and call the addin:

#' DATASET TITLE
#'
#' DATASET DESCRIPTION
#'
#' @format A data frame with 150 rows and 5 variables:
#' \describe{
#'   \item{\code{Sepal.Length}}{double. DESCRIPTION.}
#'   \item{\code{Sepal.Width}}{double. DESCRIPTION.}
#'   \item{\code{Petal.Length}}{double. DESCRIPTION.}
#'   \item{\code{Petal.Width}}{double. DESCRIPTION.}
#'   \item{\code{Species}}{integer. DESCRIPTION.}
#' }
"iris"

Matthew Lincoln

Download Details:

Author: mdlincoln
Source Code: https://github.com/mdlincoln/docthis 
License: View license

#r #rstudio #documentation 

Docthis: RStudio Addin to Create Skeleton Documentation for Functions

Help.jl: Query Documentation From Julia Prompt

Help.jl

Search through readme and documentation of packages and functions based on a query. Unlike apropos, Help uses TF-IDF instead of sub-string search.

Run update() first to build the data needed for search.

Example

julia> using Help
julia> help("Gray scale an image")
Help Results
---------
1. Images
2. ImageView
3. TestImages
4. ImageRegistration
5. SloanDigitalSkySurvey

julia> using MySQL
julia> help(MySQL, "get the last inserted id")
Help Results
---------
1. mysql_insert_id

julia> help(Base, "convert pointer to array")
Help Results
---------
1. pointer_to_array
2. oftype
3. bitpack

Download Details:

Author: nkottary 
Source Code: https://github.com/nkottary/Help.jl 
License: View license

#julia #query #documentation 

Help.jl: Query Documentation From Julia Prompt
Nat  Grady

Nat Grady

1660712880

Roxygen2: Generate R Package Documentation From inline R Comments

roxygen2  

The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to automatically generate .Rd files in man/, NAMESPACE, and, if needed, the Collate field in DESCRIPTION.

Installation

# Install devtools from CRAN
install.packages("roxygen2")

# Or the development version from GitHub:
# install.packages("devtools")
devtools::install_github("r-lib/roxygen2")

Usage

The premise of roxygen2 is simple: describe your functions in comments next to their definitions and roxygen2 will process your source code and comments to produce Rd files in the man/ directory. Here's a simple example from the stringr package:

#' The length of a string
#'
#' Technically this returns the number of "code points", in a string. One
#' code point usually corresponds to one character, but not always. For example,
#' an u with a umlaut might be represented as a single character or as the
#' combination a u and an umlaut.
#'
#' @inheritParams str_detect
#' @return A numeric vector giving number of characters (code points) in each
#'    element of the character vector. Missing string have missing length.
#' @seealso [stringi::stri_length()] which this function wraps.
#' @export
#' @examples
#' str_length(letters)
#' str_length(NA)
#' str_length(factor("abc"))
#' str_length(c("i", "like", "programming", NA))
str_length <- function(string) {
}

When you roxygenise() (or devtools::document()) your package these comments will be automatically transformed to the .Rd that R uses to generate the documentation you see when you type ?str_length.

Learn more

To get started, first read vignette("roxygen2"). Then read more about the specific package component that you want to generate:

Start with vignette("rd") to learn how document your functions with roxygen2.

vignette("rd-other") discusses how to document other things like datasets, the package itself, and the various pieces used by R's OOP systems.

vignette("rd-formatting") gives the details of roxygen2's rmarkdown support.

vignette("reuse") demonstrates the tools available to reuse documentation in multiple places.

vignette("namespace") describes how to generate a NAMESPACE file, how namespacing works in R, and how you can use roxygen2 to be specific about what your package needs and supplies.

For the Collate field in the DESCRIPTION, see ?update_collate().

Download Details:

Author: r-lib
Source Code: https://github.com/r-lib/roxygen2 
License: Unknown, MIT licenses found

#r #documentation #dev #tools 

Roxygen2: Generate R Package Documentation From inline R Comments

Tuxedo.jl: Documentation-driven Development

Tuxedo.jl

Dressing up your algorithms with documentation-driven development

Implementing technical and scientific algorithms in code starts with a thorough understanding of the problem that is being solved and how a particular algorithm solves that problem. Tuxedo provides a framework for transforming theory found in publications and technical papers into documented, testable, and usable code.

A proper and well-dressed algorithm implementation starts with naming it and documenting its purpose. Tuxedo provides a macro in the Julia environment that scaffolds documentation, function definition and unit tests.

julia> @tux MyPackage mymethod

Download Details:

Author: Milktrader
Source Code: https://github.com/milktrader/Tuxedo.jl 
License: MIT license

#julia #documentation 

Tuxedo.jl: Documentation-driven Development

Roxygen.jl: A Roxygen-like Documentation Package

Roxygen.jl

A draft implementation of a Roxygen-like package for automatically generating documentation from Julia source files.

Basic Format

The following file shows how a Julia file can use Roxygen through specially formatted comments:

#' @@name count
#'
#' @@description
#'
#' Count the number of missing values in every column of an
#' AbstractDataFrame.
#'
#' @@arg adf::AbstractDataFrame An AbstractDataFrame.
#' @@arg skip::Int The index of a column to skip.
#'
#' @@return missing::Vector{Int} The number of missing values in each column.
#' @@return success::Bool Did the operation complete successfully?
#'
#' @@examples
#'
#' df = DataFrame(A = 1:3, B = ["x", "y", "z"])
#' count(df)

function count(adf::AbstractDataFrame, skip::Int)
    return Int[], false
end

#' @@name sum
#'
#' @@description
#'
#' Sum the elements of each column of an AbstractDataFrame.
#'
#' @@arg adf::AbstractDataFrame An AbstractDataFrame.
#'
#' @@return sums::Vector{Float64} The sums of each column's entries.
#'
#' @@examples
#'
#' df = DataFrame(A = 1:3, B = ["x", "y", "z"])
#' sum(df)

function sum(adf::AbstractDataFrame)
    return Float64[]
end

This file contains Julia code as well as comments that use a set of directives, like @@arg and `@@return`` to describe properties of the function being documented. The valid directives and requirements for their use are described below:

  • @@name: The name of the function. A name directive usage must look like @@name NAME with whitespace after the directive and a single name after the initial whitespace.
  • @@exported: Is the function exported by the package being documented?
  • @@description: A short summary of the use and purpose of the function.
  • @@arg: A summary of each argument of a function in the order required by the function. Must contain argument name, argument type and a short verbal description.
  • @@field: A summary of each field of a composite type in the order required by the type's constructor. Must contain field name, field type and a short verbal description.
  • @@return: A summary of each return value of a function in the order returned by the function. Must contain value name, value type and a short verbal description.
  • @@examples: A free-form set of examples of the function or type's use.

Usage Example

To generate documentation for all .jl files in the src directory and place this documentation in the doc directory, run the following command:

using Roxygen
roxygenize("src", "doc")

Only files from the source directory that contained Roxygen documentation will give rise to files in the output directory.

Download Details:

Author: johnmyleswhite
Source Code: https://github.com/johnmyleswhite/Roxygen.jl 
License: View license

#julia #documentation 

Roxygen.jl: A Roxygen-like Documentation Package

DemoCards.jl: Let's Focus on Writing Demos

DemoCards

This package is used to dynamically generate a demo page and integrate with Documenter.jl.

Let's focus on writing demos

Overview

  • a plugin package to Documenter.jl to manage all your demos.
  • folder structure is the demo structure.
  • minimal configuration.
  • CI friendly
  • support demos in markdown and julia format.

democards workflow

The philosophy of DemoCards is "folder structure is the structure of demos"; organizing folders and files in the a structural way, then DemoCards.jl will help manage how you navigate through the pages.

examples
├── part1
│   ├── assets
│   ├── demo_1.md
│   ├── demo_2.md
│   └── demo_3.md
└── part2
    ├── demo_4.jl
    └── demo_5.jl

DemoCards would understand it in the following way:

# Examples
  ## Part1
    demo_1.md
    demo_2.md
    demo_3.md
  ## Part2
    demo_4.jl
    demo_5.jl

Read the Quick Start for more instructions.

Examples

repotheme
AlgebraOfGraphics.jl
Augmentor.jl
Bokeh.jl
FractionalDiffEq.jl
LeetCode.jl
Images.jl
ImageMorphology.jl
ReinforcementLearning.jl
Plots.jl

Caveat Emptor

The use of this package heavily relies on Documenter.jl, Literate.jl, Mustache.jl and others. Unfortunately, I'm not a contributor of any. This package also uses a lot of Regex, which I know little.

The initial purpose of this package is to set up the demo page of JuliaImages. I'm not sure how broadly this package suits the need of others, but I'd like to accept any issues/PRs on improving the usage experience.

Download Details:

Author: JuliaDocs/
Source Code: https://github.com/JuliaDocs/DemoCards.jl 
License: MIT license

#julia #card #demo #documentation 

DemoCards.jl: Let's Focus on Writing Demos

Documenter.jl: A Documentation Generator for Julia

Documenter

A documentation generator for Julia.

Installation

The package can be installed with the Julia package manager. From the Julia REPL, type ] to enter the Pkg REPL mode and run:

pkg> add Documenter

Or, equivalently, via the Pkg API:

julia> import Pkg; Pkg.add("Documenter")

Documentation

  • STABLE — documentation of the most recently tagged version.
  • DEVEL — documentation of the in-development version.

Project Status

The package is tested against, and being developed for, Julia 1.6 and above on Linux, macOS, and Windows.

Questions and Contributions

Usage questions can be posted on the Julia Discourse forum under the documenter tag, in the #documentation channel of the Julia Slack and/or in the JuliaDocs Gitter chat room.

Contributions are very welcome, as are feature requests and suggestions. Please open an issue if you encounter any problems. The contributing page has a few guidelines that should be followed when opening pull requests and contributing code.

Related packages

There are several packages that extend Documenter in different ways. The JuliaDocs organization maintains:

Other third-party packages that can be combined with Documenter include:

Finally, there are also a few other packages in the Julia ecosystem that are similar to Documenter, but fill a slightly different niche:

Download Details:

Author: JuliaDocs 
Source Code: https://github.com/JuliaDocs/Documenter.jl 
License: MIT license

#julia #docs #document 

Documenter.jl: A Documentation Generator for Julia
Rupert  Beatty

Rupert Beatty

1657918920

LaRecipe: Write Gorgeous Documentation for Your Products

LaRecipe

Write gorgeous documentations for your products using Markdown inside your Laravel app.

LaRecipe 🍪

LaRecipe is simply a code-driven package provides an easy way to create beautiful documentation for your product or application inside your Laravel app.

LaRecipe Screenshot

Official tools and assets support

Titlev1.xv2.x
LaRecipe Dark Theme❌✅
LaRecipe RTL Support❌✅
LaRecipe Feedback❌✅
LaRecipe Swagger❌✅

Getting Started

☝️ Install the package via composer.

composer require binarytorch/larecipe

✌️ Run the install command.

php artisan larecipe:install

Visit your app domain with /docs endpoint. That's it.

See full documentation

Examples

  • Zino - 🤖 Custom Arduino library made for humans.
  • Blogged - Blogged is a package provides an easy way to create beautiful blog inside your Laravel projects.
  • Wave - Wave is the perfect starter kit for building your next great idea
  • Nova ADC - Nova is a cloud-based (or on-premise) SaaS application delivery controller.
  • WooSignal - Fastest WooCommerce App Templates.
  • AddChat - All-in-one multi-purpose Chat Widget For Laravel & Codeigniter websites.
  • RoadLeagues - A cycling league management system with an API to allow data distrubution externally.
  • Raileo - Raileo helps you to monitor your website's uptime, performance and SEO
  • Put your docs here 😍👌

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

Author: Saleem-hadad
Source Code: https://github.com/saleem-hadad/larecipe 
License: MIT license

#laravel #docs #api #documentation 

LaRecipe: Write Gorgeous Documentation for Your Products
Hermann  Frami

Hermann Frami

1656073080

Serverless OpenAPI Documentation Plugin

Serverless OpenAPI Documentation Plugin  

Generates OpenAPI 3.0.0 documentation from serverless configuration files. OpenAPI is formerly known as Swagger.


Usage

This plugin requires additional configuration to use, see the "Configuration" section for how to configure the plugin to generate documentation.

Below are the commandline options to run the generator:

serverless openapi generate [options]

Options

Plugin: ServerlessOpenAPIDocumentation
openapi generate  ...................... Generate OpenAPI v3 Documentation
    --output / -o ...................... Output file location [default: openapi.yml|json]
    --format / -f ...................... OpenAPI file format (yml|json) [default: yml]
    --indent / -i ...................... File indentation in spaces [default: 2]
    --help / -h   ...................... Help

Configuration

To configure this plugin to generate valid OpenAPI documentation there are two places you'll need to modify in your serverless.yml file, the custom variables section and the http event section for each given function in your service.

This plugin is compatible with the same documentation configuration structure in serverless-aws-documentation and can run beside it.

The custom section of your serverless.yml can be configured as below:

custom:
  documentation:
    version: '1'
    title: 'My API'
    description: 'This is my API'
    models: {}

These configurations can be quite verbose; you can separate it out into it's own file, such as serverless.doc.yml as below:

custom:
  documentation: ${file(serverless.doc.yml):documentation}

functions:
  myFunc:
    events:
      - http:
          path: getStuff
          method: get
          documentation: ${file(serverless.doc.yml):endpoints.myFunc}

For more info on serverless.yml syntax, see their docs.

Models

Models contain additional information that you can use to define schemas for endpoints. You must define the content type for each schema that you provide in the models.

The required directives for the models section are as follow:

  • name: the name of the schema
  • description: a description of the schema
  • contentType: the content type of the described request/response (ie. application/json or application/xml).
  • schema: The JSON Schema (website) that describes the model. You can either use inline YAML to define these, or refer to an external schema file as below
custom:
  documentation:
    models:
      - name: "ErrorResponse"
        description: "This is an error"
        contentType: "application/json"
        schema: ${file(models/ErrorResponse.json)}
      - name: "PutDocumentResponse"
        description: "PUT Document response model (external reference example)"
        contentType: "application/json"
        schema: ${file(models/PutDocumentResponse.json)}
      - name: "PutDocumentRequest"
        description: "PUT Document request model (inline example)"
        contentType: "application/json"
        schema:
          $schema: "http://json-schema.org/draft-04/schema#"
          properties:
            SomeObject:
              type: "object"
              properties:
                SomeAttribute:
                  type: "string"

Functions

To define the documentation for a given function event, you need to create a documentation attribute for your http event in your serverless.yml file.

The documentation section of the event configuration can contain the following attributes:

  • summary: a short description of the method
  • description: a detailed description of the method
  • tags: an array of tags for this event
  • deprecated: boolean indicator that indicates clients should migrate away from this function
  • requestBody: contains description of the request
    • description: a description of the request body
  • requestModels: a list of models to describe the request bodies (see requestModels below)
  • queryParams: a list of query parameters (see queryParams below)
  • pathParams: a list of path parameters (see pathParams below)
  • cookieParams: a list of cookie parameters (see cookieParams below)
  • methodResponses: an array of response models and applicable status codes
    • statusCode: applicable http status code (ie. 200/404/500 etc.)
    • responseBody: contains description of the response
      • description: a description of the body response
    • responseHeaders: a list of response headers (see responseHeaders below)
    • responseModels: a list of models to describe the request bodies (see responseModels below) for each Content-Type
functions:
  createUser:
    handler: "handler.create"
    events:
      - http:
        path: "create"
        method: "post"
        documentation:
          summary: "Create User"
          description: "Creates a user and then sends a generated password email"
          requestBody:
            description: "A user information object"
          requestModels:
            application/json: "PutDocumentRequest"
          pathParams:
            - name: "username"
              description: "The username for a user to create"
              schema:
                type: "string"
                pattern: "^[-a-z0-9_]+$"
          queryParams:
            - name: "membershipType"
              description: "The user's Membership Type"
              schema:
                type: "string"
                enum:
                  - "premium"
                  - "standard"
          cookieParams:
            - name: "SessionId"
              description: "A Session ID variable"
              schema:
                type: "string"
          methodResponses:
            - statusCode: 201
              responseBody:
                description: "A user object along with generated API Keys"
              responseModels:
                application/json: "PutDocumentResponse"
            - statusCode: 500
              responseBody:
                description: "An error message when creating a new user"
              responseModels:
                application/json: "ErrorResponse"

queryParams

Query parameters can be described as follow:

  • name: the name of the query variable
  • description: a description of the query variable
  • required: whether the query parameter is mandatory (boolean)
  • schema: JSON schema (inline or file)
queryParams:
  - name: "filter"
    description: "The filter parameter"
    required: true
    schema:
      type: "string"

pathParams

Path parameters can be described as follow:

  • name: the name of the query variable
  • description: a description of the query variable
  • schema: JSON schema (inline or file)
pathParams:
  - name: "usernameId"
    description: "The usernameId parameter"
    schema:
      type: "string"

cookieParams

Cookie parameters can be described as follow:

  • name: the name of the query variable
  • description: a description of the query variable
  • required: whether the query parameter is mandatory (boolean)
  • schema: JSON schema (inline or file)
cookieParams:
  - name: "sessionId"
    description: "The sessionId parameter"
    required: true
    schema:
      type: "string"

requestModels

The requestModels property allows you to define models for the HTTP Request of the function event. You can define a different model for each different Content-Type. You can define a reference to the relevant request model named in the models section of your configuration (see Defining Models section).

requestModels:
  application/json: "CreateRequest"
  application/xml: "CreateRequestXML"

methodResponses

You can define the response schemas by defining properties for your function event.

For an example of a methodResponses configuration for an event see below:

methodResponse:
  - statusCode: 200
    responseHeaders:
      - name: "Content-Type"
        description: "Content Type header"
        schema:
          type: "string"
    responseModels:
      application/json: "CreateResponse"
      application/xml: "CreateResponseXML"

responseModels

The responseModels property allows you to define models for the HTTP Response of the function event. You can define a different model for each different Content-Type. You can define a reference to the relevant response model named in the models section of your configuration (see Defining Models section).

responseModels:
  application/json: "CreateResponse"
  application/xml: "CreateResponseXML"

responseHeaders and requestHeaders

The responseHeaders/requestHeaders section of the configuration allows you to define the HTTP headers for the function event.

The attributes for a header are as follow:

  • name: the name of the HTTP Header
  • description: a description of the HTTP Header
  • schema: JSON schema (inline or file)
responseHeaders:
  - name: "Content-Type"
    description: "Content Type header"
    schema:
      type: "string"
requestHeaders:
  - name: "Content-Type"
    description: "Content Type header"
    schema:
      type: "string"

Example configuration

Please view the example serverless.yml.

Install

This plugin works for Serverless 1.x and up. Serverless 0.5 is not supported.

To add this plugin to your package.json:

Using npm:

npm install serverless-openapi-documentation --save-dev

Using Yarn:

yarn add serverless-openapi-documentation --dev

Next you need to add the plugin to the plugins section of your serverless.yml file.

plugins:
  - serverless-openapi-documentation

You can confirm the plugin is correctly installed by running:

serverless | grep -i "ServerlessOpenAPIDocumentation"

It should return ServerlessOpenAPIDocumentation as one of the plugins on the list.

Note: Add this plugin after serverless-offline to prevent issues with String.replaceAll being overridden incorrectly.


The configuration is inspired by the format used in serverless-aws-documentation.

Works well with Lincoln OpenAPI Renderer.


Author: Temando
Source Code: https://github.com/temando/serverless-openapi-documentation 
License: MIT license

#serverless #openapi #documentation 

Serverless OpenAPI Documentation Plugin

Deprecated, Please Use The TypeScript-Website Repo instead

TypeScript-Handbook Repo Deprecated

The handbook has moved into the new TypeScript website repo, you can find the revised and updated handbook pages in /packages/documentation in that repo.


TypeScript-Handbook

Build Status

The TypeScript Handbook is a comprehensive guide to the TypeScript language. It is meant to be read online at the TypeScript website or directly from this repository.

For a more formal description of the language, see the latest TypeScript Language Specification.

How To Contribute

TypeScript-Handbook is accepting contributions. If you've submitted a PR for an existing issue, please post a comment in the issue to avoid duplication of effort. See our CONTRIBUTING file for more information - it also contains guidelines for how to submit a PR.

Author: Microsoft
Source Code: https://github.com/microsoft/TypeScript-Handbook 
License: Apache-2.0 license

#typescript #documentation 

Deprecated, Please Use The TypeScript-Website Repo instead
Rocio  O'Keefe

Rocio O'Keefe

1654239725

Docs.page: Instant Open Source Docs with Zero Configuration

 Instant Open Source docs with zero configuration.

About

docs.page is a free Open Source project, allowing you to create instant, fast, beautiful documentation with zero configuration.

Documentation is an important aspect for many projects, however creating a custom documentation website for each project is time consuming. Many common solutions to problems have to be duplicated, along with dealing with overheads such as website maintenance & hosting.

Solutions such as Jekyll, Docusaurus, docsify and many others are great projects, however still require custom setup for each project.

docs.page is designed to deliver instant documentation websites, with the content sourced directly from any public GitHub repository. Features include:

  • Configurable: Add your own logo, theme, analytics, navigation and more with a simple config file.
  • Previewing: View the documentation of any branch, pull request or specific commit, and a new Local Preview Mode.
  • GitHub Bot: Install our GitHub bot to automatically get a URL to pull request documentation previews.
  • Components: Powered by MDX, use React components such as Tabs (useful for projects with multiple languages) directly in your docs.
  • Search: Easily add full search support powered by DocSearch.
  • Custom Domains: Serve your documentation using your own domain.

Other useful features include:

  • Global variable injection (for managing common variables across the project).
  • Displaying assets using GitHub.
  • Dark/Light mode.
  • Responsive.
  • Code block highlighting and content copying.
  • Page redirects.
  • Per-page metadata support via Frontmatter.

Should I use docs.page?

docs.page is a simple way to generate a documentation with zero effort. It generally works for documentation websites with a lot of Markdown based content. If you require features which are more specific to your own project a custom solution might work better.

Use this package as an executable

Install it

You can install the package from the command line:

dart pub global activate docs_page

Use it

The package has the following executables:

$ docs_page

example/main.dart

import 'package:docs_page/src/typedoc.dart';

void main() async {
  final rootAst = await getTypedocJson();

  await generate(ast: rootAst);
}

Homepage • Documentation

Author: invertase
Source Code: https://github.com/invertase/docs.page 
License: Apache-2.0 license

#flutter #dart #documentation 

Docs.page: Instant Open Source Docs with Zero Configuration
Reid  Rohan

Reid Rohan

1651692180

React-styleguidist: Isolated React Component Development Environment

Isolated React component development environment with a living style guide

React Styleguidist is a component development environment with hot reloaded dev server and a living style guide that you can share with your team. It lists component propTypes and shows live, editable usage examples based on Markdown files. Check out the demo style guide.

React Styleguidist in action

Usage

Advanced documentation

Examples

Showcase

Real projects using React Styleguidist:

Integration with other tools

Third-party tools

Resources

Change log

The change log can be found on the Releases page.

Contributing

Everyone is welcome to contribute. Please take a moment to read the contributing guidelines and the developer guide.

Author: Styleguidist
Source Code: https://github.com/styleguidist/react-styleguidist 
License: MIT License

#react #javascript #documentation 

React-styleguidist: Isolated React Component Development Environment

Cómo Escribir Una Buena Documentación API

Imagina que acabas de comprar un nuevo sistema de cine en casa y vas a configurarlo. ¿Qué haces primero?

Gracias a Dios que tienes un práctico manual del dispositivo para ayudarte. Solo tienes que seguir los pasos detallados en el manual y ¡voilà! Su sistema de cine en casa está listo para reproducir sus canciones favoritas.

Al igual que el manual de un dispositivo lo guía a través de la configuración y la instalación, la documentación de la API puede guiarlo a través de la configuración de una API.

¿Qué es la documentación de la API?

Antes de profundizar en la documentación de la API, permítanme explicar brevemente qué es una API y sus funciones básicas.

API es un acrónimo de Interfaz de programación de aplicaciones.

7020614

Conexión de dispositivos a bases de datos vía API

Ya sea que sea un codificador principiante o un desarrollador avanzado, encontrará este término a menudo en su viaje de desarrollo de software. Es el puente entre su computadora, teléfono móvil o aplicación y los recursos externos.

En otras palabras, las API le dan a su software la capacidad de interactuar con otros programas de software, bases de datos o recursos. En lugar de escribir el programa para una característica particular de su aplicación, puede consumir una API fácilmente disponible de una característica similar.

Muchas API son públicas (gratuitas), mientras que otras son privadas y requieren el pago de una clave privada que le permite acceder a la API. Existen diferentes tipos de API como REST (Transferencia de estado representacional), SOAP (Protocolo simple de acceso a objetos) y otros.

Continuando, entonces, ¿qué es la documentación de la API? Bueno, es una guía escrita que indica las funciones de la API, cómo integrarla en su programa y casos de uso de la API, junto con ejemplos.

Tenga en cuenta que la documentación de la API es contenido técnico. Esto significa que contendrá algunos términos técnicos, pero aún debe ser legible y fácil de entender.

¿Quién debe escribir la documentación de la API?

Las API son creadas por desarrolladores de software. Dado que los desarrolladores de software están directamente involucrados en la creación y el uso de las API, es más fácil para ellos crear la documentación.

La desventaja de que los desarrolladores de software escriban documentación de API es que escriben desde un ángulo muy técnico, lo que puede hacer que el documento sea bastante difícil de comprender. Otro problema es que el desarrollador de la API tardará más en crear el documento mientras desarrolla la API.

Entonces, una buena alternativa es asignar la tarea de documentación de la API a un redactor técnico. Un escritor técnico es alguien que combina la experiencia en la redacción de contenido y el conocimiento técnico para producir documentación que no solo es técnica, sino también informativa y comprensible.

El escritor técnico aprende sobre la API de los desarrolladores de la API, luego crea tutoriales, ejemplos y otro contenido con fines de documentación.

Mientras tanto, los desarrolladores de la API supervisan al redactor técnico para asegurarse de que la documentación escrita sea precisa y pueden proporcionar más información al redactor cuando sea necesario.

El objetivo es que todos trabajen juntos para producir documentación que explique completamente la API y guíe a los usuarios sin confusión.

Si está interesado en escribir documentación para una API, pero no sabe dónde o cómo comenzar, este artículo lo ayudará a comenzar.

Puedo sentir tu emoción desde aquí, ¡así que vamos a sumergirnos!

Cómo comenzar a escribir documentación API

Al escribir la documentación de la API, comience creando varios esquemas. Esto le dará una visión general de lo que pretende escribir.

Lo siguiente es recopilar información para cada uno de los esquemas que creó. Esto se puede lograr obteniendo la descripción de la API, el idioma utilizado, otras referencias y ejemplos de casos de los desarrolladores de la API. También puede ver una demostración en vivo de la API para que tenga una experiencia de primera mano de cómo funciona.

Por último, combine los detalles que reunió y organícelos en una secuencia lógica.

Recuerde revisar su documento y compartirlo con los desarrolladores de API para cualquier corrección o adición antes de hacerlo público.

Ahora que sabe por dónde empezar, ¿cómo puede juntar las partes para que se conviertan en un todo significativo?

Qué incluir en la documentación de la API

API-Doc

1. Una visión general

Esto es similar a la página de resumen de un informe de proyecto.

La descripción general debe contener un resumen de la API y el problema que está resolviendo. También podría incluir los beneficios de usar esta API en particular sobre otras API similares.

2. Tutoriales

Esta es la parte principal de la documentación.

Debe incluir los diferentes formatos de contenido que está utilizando para explicar el concepto de la API al usuario. También puede incluir enlaces de referencia y una guía paso a paso para integrar la API y consumirla para que funcione correctamente.

3. Ejemplos

Una vez que haya explicado cómo funciona la API y/o proporcionado los pasos detallados, es una buena idea mostrar ejemplos de llamadas, respuestas, manejo de errores y otras operaciones que tienen que ver con la forma en que el desarrollador interactúa con la API.

4. Glosario

Aunque esto es opcional, recomiendo agregar una página de glosario para la documentación de su API.

Para evitar aburrir al usuario con bloques de texto largos, las explicaciones de varios términos, esquemas, imágenes, etc., que se utilizan en la documentación se pueden enviar al glosario. Luego puede hacer referencia a estas cosas en la documentación y vincular al glosario.

Una PC y un bloc de notas.

Cómo escribir documentación API útil

Conoce la API

Como acabamos de discutir, debe tener conocimiento de primera mano de la API que está documentando. Recuerde, su objetivo es guiar a los usuarios potenciales que quizás no tengan ningún conocimiento sobre la API. No querrías confundirlos, ¿verdad?

Si tiene una comprensión sólida de la arquitectura, la funcionalidad y otra información vital del producto, podrá escribir la parte de descripción del producto de la API de manera efectiva sin hacer conjeturas.

Si no está bien informado o no está completamente convencido acerca de la API sobre la que está escribiendo, tómese un tiempo para investigar y recopilar la mayor cantidad de información posible. Utilice la API usted mismo para obtener información importante sobre cómo funciona.

Usar contenido relacionado

La documentación de la API no se limita únicamente a las guías escritas. Puede usar videos cortos o diapositivas de PowerPoint para ilustrar la integración de la API.

Indique diferentes casos de uso mientras escribe la documentación. Esto ayudará a los lectores a reconocer cuál es similar al suyo, o encontrar uno con el que puedan relacionarse fácilmente.

Además, incluya algunos fragmentos de código donde y cuando crea que son necesarios. Esto hará posible que los lectores lo sigan a medida que avanzan en la documentación. Como dice el dicho popular: "Dime y lo olvido. Enséñame y lo recuerdo. Involúcrame y lo aprendo".

Sea claro, incluso si necesita ser técnico

Las API son guías para software o hardware, por lo que deberá usar algunos términos técnicos al escribir la documentación. Si intenta ser un escritor técnico, resista la tentación de ser ambiguo.

Un buen documento no es uno con construcciones gramaticales complejas, sino uno que sea identificable, directo y claro. Solo puede relacionarse cuando está escrito en un lenguaje simple y comprensible.

La documentación de su API debe estar en la forma más simple posible, pero no debe omitir ningún detalle importante. Además, asegúrese de explicar los acrónimos y los términos tecnológicos la primera vez que los use, o póngalos en un glosario hacia el final de la documentación.

Detallar la guía

La documentación es más fácil de entender si el contenido está detallado. Esta es una razón importante para escribir concisamente.

Numerar o detallar la guía en pasos ayuda al usuario a determinar qué hacer en cada momento. Es similar a leer el alfabeto de la A a la Z.

Con pasos claros, los usuarios pueden regresar fácilmente si se encuentran con un error.

Comprobar errores

Por muchas veces que lea un documento, siempre habrá algo para cambiar, actualizar o incluso eliminar. Esta es una experiencia típica con los escritores y no debería molestarte.

El oro pasa por varios hornos de fuego antes de ser refinado. Digamos que su documentación debe pasar por un proceso similar (aunque no un horno de fuego) para que salga como un documento bien preparado.

Un proceso de revisión exhaustivo puede ayudarlo a minimizar cualquier error y producir una documentación clara.

Las mejores herramientas para la documentación de API

Escribir la documentación de la API puede llevar mucho tiempo y ser difícil de mantener. Pero una buena herramienta de documentación puede aliviar la mayoría, si no todos, estos problemas.

Existen numerosas herramientas para facilitar su recorrido por la documentación de la API. El beneficio de usar herramientas son las características de colaboración y las plantillas estándar que brindan estas herramientas, en lugar de comenzar desde cero.

A continuación se muestra una lista de algunas herramientas populares y sus ventajas.

Cartero

Postman es una plataforma para crear y mantener API con funciones para crear documentación de API.

Postman utiliza su herramienta de documentación legible por máquina para hacer que el proceso de documentación de la API sea más fácil y rápido. Puede registrarse en Postman de forma gratuita e instalarlo en su PC.

Aunque Postman proporciona actualizaciones para toda la documentación de la API que produce automáticamente, su interfaz de usuario puede ser difícil de entender al principio.

apuestodox

DapperDox es una herramienta de documentación API de código abierto que ofrece varios temas para crear su documento. Esta herramienta combina diagramas, especificaciones y otros tipos de contenido para brindarle una mejor documentación.

Tiene la ventaja de permitir a los autores escribir en Markdown con sabor a GitHub, pero las actualizaciones de esta herramienta son irregulares.

SwaggerHub

SwaggerHub es una herramienta de documentación de API popular para muchos escritores técnicos porque es interactiva y fácil de usar.

Aunque es apto para principiantes, requiere el pago de cualquier otra cosa que no sea el uso personal. Entonces, si es parte de una organización y quiere usar SwaggerHub, su organización tendrá que pagar por ello.

Ya sea que esté seleccionando las herramientas enumeradas aquí o una alternativa, debe considerar lo siguiente:

  • ¿En qué configuración usará la herramienta? ¿Es para uso personal o como parte de una organización?
  • ¿Qué tan técnico eres? ¿Eres principiante o experto?
  • ¿Cómo es la interfaz de usuario y la experiencia de usuario?

Algunos ejemplos asombrosos de API Docs

A continuación se encuentran algunos documentos de API que lo inspirarán a comenzar a escribir excelentes documentos de API. Cada uno de estos documentos detalla el uso de la API del producto para los desarrolladores en pasos sencillos y términos comprensibles.

Documentos de la API de GitHub

GitHub ofrece documentación realmente útil, lo cual no sorprende. Echa un vistazo a sus documentos API aquí:

https://docs.github.com/en/rest/guides/primeros-pasos-con-el-resto-api

REST API es una API popular utilizada por los desarrolladores para acceder a datos desde la web o una base de datos. Esta documentación de Github incluye una descripción general, guías e incluso código sobre cómo usar la API REST en su programa.

La parte interesante de estos documentos es que puede entenderlos fácilmente independientemente de su nivel de habilidad.

Documentos de la API de Paystack

Cree increíbles experiencias de pago con la API de Paystack

¿Está creando una aplicación que requiere pago? Paystack es una solución fintech para pagos. Su equipo brinda información detallada para desarrolladores sobre cómo usar la API de Paystack en sus programas. Es más como proporcionar un manual sobre el uso de la API para evitar confusiones al consumir la API en su programa.

Documentos de la API de Twitter

https://developer.twitter.com/en/docs/twitter-api

La documentación de la API de Twitter explica cómo los desarrolladores pueden interactuar con la aplicación. Los documentos detallan claramente diferentes apartados (usuario, tuits, mensajes directos, etc.) y su funcionamiento.

Aunque se requiere permiso de acceso para obtener más información, puede acceder a los básicos con solo hacer clic en el enlace.

Conclusión

La documentación establece cómo funciona una herramienta para que otros puedan usarla correctamente. Los documentos de API no siempre son fáciles de crear, pero no es tan difícil crear documentación útil como podría pensar.

Solo recuerde: comience escribiendo su primer borrador, mejórelo diariamente y busque ayuda de mentores o colegas senior cuando esté atascado.

Ahora continúe y escriba la documentación de la API que se enviará con el próximo producto de clase mundial.

Fuente: https://www.freecodecamp.org/news/how-to-write-api-documentation-like-a-pro/

#api #documentation 

Cómo Escribir Una Buena Documentación API