Contains a programmatic API for generating Markdown documentation from an API report generated by API-Extractor.
It is similar to API-Documenter and is heavily based upon it and uses it under the hood, but is designed to be more extensible and can be used programmatically.
Note: this library does not currently offer a Command Line Interface (CLI). One may be added in the future, but for now this library is intended to be consumed programmatically.
To get started, install the package by running the following command:
npm i @fluid-tools/api-markdown-documenter -DThis library is intended to be highly customizable. That said, it is also intended to be easy to use out of the box.
Are you using API-Extractor?
Are you already generating .api.json report files as a part of your build?
If yes, create a file called api-markdown-documenter.js and paste the following code:
const { readModel, renderFiles } = require("@fluid-tools/api-markdown-documenter");
const inputDir = "<PATH-TO-YOUR-DIRECTORY-CONTAINING-API-REPORTS>";
const outputDir = "<YOUR-OUTPUT-DIRECTORY-PATH>";
// Create the API Model from our API reports
const apiModel = await readModel(inputDir);
const config = {
apiModel,
uriRoot: ".",
};
await renderFiles(config, outputDir);The above script can be invoked as an npm script by adding the following to your package.json's scripts property:
"generate-api-docs": "node ./api-markdown-documenter.js"The above steps omit many of the configuration options exposed by the library. For more advanced usage options, see the following sections.
This package contains 2 primary, programmatic entry-points for generating documentation:
The renderDocuments function accepts an ApiModel representing the package(s) of a repository, and generates a sequence of "Document" objects representing the resulting documentation based on the other provided configuration options.
These objects include information about the page item, its documentation contents, and the intended output file path the document file should be rendered to, based on provided policy options.
The input ApiModel here will generally be the output of API-Extractor.
The renderFiles function operates like renderDocuments, but writes the resulting documents to disk as files based on the provided configuration options.
This function also accepts a MarkdownEmitter object that does the conversion from DocNode trees to a Markdown stream that will ultimately be rendered to file.
Both of the rendering APIs above take as input an ApiModel object that describes the API suite being processed.
To generate an API model from .api.json files generated by API-Extractor, see the loadModel function, which can generate an ApiModel for you, given a path to a directory containing the API reports.
If you are using the renderDocuments option described above, one option for emitting Markdown string content is to use the emitMarkdown function.
It accepts a MarkdownDocument object as input, and outputs a string representing the final Markdown content.
Note: you can also accomplish this by just using renderFiles if you are using default configuration / emitter options.
As mentioned above, this library was designed in an attempt to be highly flexible and configurable.
If you look at the configuration type MarkdownDocumenterConfiguration, you will see that it offers quite a few degrees of freedom.
But fret not! The vast majority of these options have default values that have been crafted to produce high quality documentation for your library with minimal specification.
apiModel: This is the ApiModel representing the API suite. It is generated by processing the.api.jsonreport files generated byAPI-Extractor.uriRoot: This is the root URI under which the generated documentation will be published. It will be used when generating links for API content docs.
- Intro sandbox (api report)
- Remove leading blank line in documents
- Excessive blank lines in Signature sections
- Fix links to the same file (only need heading component, not file path)
- This will require plumbing down a context document item, so we can easily determine if the document to which the link is being generated is the same as the document being linked to.
- Replace DocNode output / MarkdownEmitter with Markdown AST trees and simple interface for rendering those trees to a stream
- Support placing documents within their own hierarchy (support for the "index" model used by systems like DocFX)
- Pre-canned policies (flat, index, adjacency)
- Handle multiple package entrypoints
There are many ways to contribute to Fluid.
- Participate in Q&A in our GitHub Discussions.
- Submit bugs and help us verify fixes as they are checked in.
- Review the source code changes.
- Contribute bug fixes.
Detailed instructions for working in the repo can be found in the Wiki.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.
Not finding what you're looking for in this README? Check out our GitHub Wiki or fluidframework.com.
Still not finding what you're looking for? Please file an issue. Thank you!
This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks or logos must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.