Automates publishing documentation, for use continuous integration and continuous deployment
npm install autodocsautodocsAutomates publishing API docs for NodeJs projects, useful for continuous integration.
Install this tool as a devDependency in your NodeJs project,
and add a autodocs script to your project's package.json.
This tool is agnostic to how you use to generate documentation -
it simply executes npm run generatedocs.
Similarly, this tool is agnostic to how you choose to test your generated documentation -
it simply executes npm run testdocs.
For example, if you are using this project to publish documentation
generated by yuidocjs, you would run:
``bash`
npm install --save-dev autodocs yuidocjs
... and then add the following the scripts section of package.json:
`json`
"scripts": {
"generatedocs": "node ./node_modules/yuidocjs/lib/cli .",
"testdocs": "node ./got-or-not.js .",
"autodocs": "node ./node_modules/autodocs"
}
An easy way to test whether you have generated
the files that you expect is to use
got-or-not.
Configure your CI environment to run the autodocs script.travis.yml
after the project has successfully built.
For example, if using Travis, add this to your
`yaml`
after_success:
- npm run autodocs
Remember that autodocs is responsible for running generatedocs
when it determines that it should.
There is no need to include or testdocs in your CI script -autodocs
only ,generatedocs
and that will run and testdocs
when appropriate.
autodocs generates its own documentation.
The API that autodocs exposes is designed to be fully operable by means ofautodocs
environment variables.
This is the case because that is what continuous integrations environments,
which is where should be getting invoked from most of the time,
use.
The API documentation for autodocs
documents the full set of options available.
The list below is merely a subset - just the most important ones.
In addition to this, publishing also needs a few environment variables to be set:
- GH_TOKEN
- Use an encrypted Github access token
-
- Optional, set to override
- Default: Inferred from set by TravisGH_REPO
- Github user name
-
- Optional, set to override
- Default: Inferred from set by TravisDOCUMENT_JOB_INDEX
- Github repository name
-
- Optional, set to override
- default:
- Documentation will be generated only on one of the jobs
for each build, use this to specify which one.
- :documentation
- default:
- to specify folder where documentation is generated
- this represents the location of the input for ,generatedocs
and it expects the files needed to be published to be here after running the scriptFLAG_PUBLISH_IN_ROOT
-
- default:
- whether to publish in the root folder
- by default, documents will be published in
- if using this module to publish something like a blog,
instead of versioned software documentation,
you should set this flag to
-
- default:
- whether there are any assets to copy
- set to only if intending to use DOCUMENT_ASSETS
-
- default:
- list of files and folders (bash style) to copy into the root of the branchDOCUMENT_PUBLISH_FOLDER
- these files will be copied to the root, not the
Your Git repository can have many different branches being pushed,
but you only have one published documentation,
so for DOCUMENT_BRANCH,master
select the branch for which documentation should be published.
It makes the most sense to select the branch from which releases are cut.
If you are using either Git Flow or the standard Github branching strategies,
it makes the most sense to leave this as .
If your project has built successfully on CI,
and you have not overridden the default values for publish folder,
visit http://GH_USER.github.io/GH_REPO/api/VERSION.
For example: bguiz.github.io/plugin-registry/api/0.6
The value of VERSION` includes the major and minor versions only,
because semver (semantic versioning) principles state that
if there are any API changes, the major or minor version numbers should be bumped;
and conversely, that when a patch version number is bumped,
it implies that there have not been any API changes.
This is done so as to be able to provide references for multiple versions
of your projects at the same time,
which can be handy for users who are unable to upgrade,
and also for users determining what has changed from the version
they are currently using to the one they wish to switch to.
This is just the default behaviour,
and can be configured to do something else via environment variables.
See the API documentation for the details.
This repository uses the git flow branching strategy.
If you wish to contribute, please branch from the develop branch -
pull requests will only be requested if they request merging into the develop branch.
When contributing see also the items described in the
roadmap.
Maintained by Brendan Graetz
GPL-3.0