A CLI tool that scaffolds API documentation based on JSON HyperSchemas.
This version of
docahas been deprecated in favor of
@cloudflare/doca, in the json-schema-tools repository. While
@cloudflare/docais conceptually the same, the back-end tools use a different format that retains compatibility with JSON Schema, so the theme requirements are different
@cloudflare/docadoes not yet have a fully functioning theme, so this package is still the produciton-ready one. But we will be implementing feature requests on the new code, and moving most open issues to the new repo whenever it makes sense.
Doca bootstraps a full-fledged web app based on React and Webpack. Getting the final documentation is as easy as typing few commands or you can dive deeper and create your own completely different layout. Read the introductory blog post.
The doca suite is under active development! See our Road Map for details.
Doca consists of: * a command line tool (this repository) * themes (standalone node modules such as doca-bootstrap-theme) * webpack loaders (background node modules you can mostly forget about) * json-schema-loader loads schemas and tracks dependencies * json-schema-example-loader converts schemas into the format expected by the themes
Here is a diagram:
npm install doca -g
You need to use Node.js 4+ and Npm 2+.
doca init [-i schema_folder] [-o project_folder] [-t theme_name]
It goes through the current dir (or
schema_folder), looks for
**/*.jsonfiles and generates
/project_folder). Doca has modular 3rd party themes. The default one is doca-boostrap-theme. It can be aliased just as
bootstrap. This command should be used only once when you need to bootstrap your project.
doca theme newTheme project
This sets a different theme
project. It has two steps: - it calls
npm install newTheme --saveinside of
project- renames all
doca-newTheme-themeThis can make destructive changes in your project. Always use version control!
A note about package scopes: While non-scoped themes can be referenced by their simple name (e.g.
doca-newTheme-theme), scoped theme packages such as
@myscope/doca-abc-thememust be passed as the full package name, including the scope.
This lists the commands and their syntax.
git clone [email protected]:cloudflare/doca.git cd doca/example doca init cd documentation npm install
That's it! Once installed, there are three ways to run the project:
npm start open http://localhost:8000
npm install npm run build open build/index.html
npm install npm run build:nojs open build/index.html
Do you need to add more schemas or change their order? Edit the file
Do you want to change the generic page title or make CURL examples nicer? Edit the file
Themes are additional node modules. Doca theme is just a set of React components and style sheets. At CloudFlare we use our own custom private CF theme. You can see it here in action. We have also open source a theme based on Twitter Bootstrap. It is used as a default option for doca.
The Bootstrap theme also contains a detailed description about how to fork and create your own theme . It's pretty easy!
Currently, themes include nearly all UI functionality. We are working on allowing CSS-level themes while sharing the UI structure. See our road map for details.
If you create one, please send a PR with link.
You can install any theme with the command
doca theme THEME_NAME documentation
For non-scoped theme packages, you can use full name
doca-THEME_NAME-themeor just shortcut
For scoped theme packages, you must use the full name