Autodocs
Table of Contents
- Methods
-
Properties
- DOCUMENT_ASSETS
- DOCUMENT_BRANCH
- DOCUMENT_GENERATE_HOOK
- DOCUMENT_GENERATED_FOLDER
- DOCUMENT_JOB_INDEX
- DOCUMENT_PUBLISH_FOLDER
- DOCUMENT_PUBLISH_FOLDER_ROOT
- DOCUMENT_PUBLISH_SUBFOLDER
- DOCUMENT_TEST_HOOK
- FLAG_ALL_PAGE
- FLAG_CLEAN_DOCUMENT
- FLAG_COPY_ASSETS
- FLAG_LATEST_PAGE
- FLAG_PUBLISH_IN_ROOT
- FLAG_PUBLISH_ON_RELEASE
- FLAG_SKIP_GENERATE
- FLAG_SKIP_PUBLISH_RUN
- FLAG_SKIP_PUSH
- FLAG_SKIP_TEST
- FLAG_STRIP_TOKEN_OUTPUT
- GIT_EMAIL
- GIT_USER
- MAJOR_VERSION
- MINOR_VERSION
- PATCH_VERSION
- PROJECT_DIR
- SELECT_CI
- SELECT_PUBLISH
Methods
init
()
Initialisation step for Autodocs
Used to check/ set any Autodocs environment variables
run
()
Will determine which continuous integration environment and publishing environment to use, and then run those appropriately.
Currently, the supported ones are:
- Continuous Integration (
SELECT_CI
):travis
- Publishing Environment (
SELECT_PUBLISH
):github-pages
Runs various environment variables checks and sets defaults where appropriate. Then tests whether this particular build should trigger publishing the documentation, and if so fires the publish script
Properties
DOCUMENT_ASSETS
String (Environment Variable)
list of files and folders (bash style) to copy into the root of the gh-pages
branch
these files will be copied to the root, not the DOCUMENT_PUBLISH_FOLDER
Default: ''
DOCUMENT_BRANCH
String (Environment Variable)
Documentation will be generated only when this branch is pushed
Default: 'master'
DOCUMENT_GENERATE_HOOK
String (Environment Variable)
The name of the npm script to run, expecting the documentation to get generated. For example:
npm run ${DOCUMENT_GENERATE_HOOK}
Default: 'generatedocs'
DOCUMENT_GENERATED_FOLDER
String (Environment Variable)
After the documentation generation script is run, autodocs expects to find its output in this folder. The files located here will get published.
Default: 'documentation'
DOCUMENT_JOB_INDEX
String (Environment Variable)
Documentation will be generated only on one of the jobs for each build, use this to specify which one.
Default: '1'
DOCUMENT_PUBLISH_FOLDER
String (Environment Variable)
Joins DOCUMENT_PUBLISH_FOLDER_ROOT
with DOCUMENT_PUBLISH_SUBFOLDER
to get a concrete path to publish the documentation.
Default: '{{DOCUMENT_PUBLISH_FOLDER_ROOT}}/{{DOCUMENT_PUBLISH_SUBFOLDER}}'
DOCUMENT_PUBLISH_FOLDER_ROOT
String (Environment Variable)
All documentation will be published under this root directory
This can be used for non-version-specific documentation
Default: 'api'
DOCUMENT_PUBLISH_SUBFOLDER
String (Environment Variable)
The documentation will be published in this subdirectory of the root directory.
This can be used for version-specific documentation
Default: '{{MAJOR_VERSION}}.{{MINOR_VERSION}}'
DOCUMENT_TEST_HOOK
String (Environment Variable)
The name of the npm script to run, expecting the documentation to get tested. For example:
npm run ${DOCUMENT_TEST_HOOK}
Default: 'testdocs'
FLAG_ALL_PAGE
String (Environment Variable)
By default, this will publish an all page, whose purpose is simply to list and link to all published API versions
Assuming default values for other configurations,
if the versions of the project are currently 0.1
, 0.2
, 0.3
, and 1.0
http://USER.github.io/REPO/api/all/
- This URL will be published with an
index.html
file that links to:http://USER.github.io/REPO/api/0.1/
http://USER.github.io/REPO/api/0.2/
http://USER.github.io/REPO/api/0.3/
http://USER.github.io/REPO/api/1.0/
Set to false
to disable this behaviour.
Default: 'true'
FLAG_CLEAN_DOCUMENT
String (Environment Variable)
Whether to clean up afterward, by deleting the directory that was published
Default: 'false'
FLAG_COPY_ASSETS
String (Environment Variable)
Whether there are any assets to copy.
Set to true
only if intending to use DOCUMENT_ASSETS
.
Default: 'false'
FLAG_LATEST_PAGE
String (Environment Variable)
By default, this will publish a latest page, whose purpose is simply to redirect to the most recently publish API version
Assuming default values for other configurations,
if the version of the project is currently 1.2.3
,
http://USER.github.io/REPO/api/latest/
- This URL will be published with an
index.html
file that redirects to: http://USER.github.io/REPO/api/1.2/
Set to false
to disable this behaviour.
Default: 'true'
FLAG_PUBLISH_IN_ROOT
String (Environment Variable)
If set to 'true'
DOCUMENT_PUBLISH_FOLDER
is ignored,
and the document is published in the root folder instead.
If using this module to publish something like a blog,
instead of versioned software documentation,
you should set this flag to true
.
Default: 'false'
FLAG_PUBLISH_ON_RELEASE
String (Environment Variable)
By default, publish will occur when a branch is pushed.
When this flag is set to true
,
publish will occur when a tag is pushed instead.
Default: 'false'
FLAG_SKIP_GENERATE
String (Environment Variable)
Set to true to skip step where documentation is generated. i.e. Do not run
npm run generatedocs
This is useful for testing and debugging purposes. Leaving this on in a CI environment would defeat the purpose of autodocs
Default: 'false'
FLAG_SKIP_PUBLISH_RUN
String (Environment Variable)
Set to true to skips the entirety of the CI publish run function. None of the publishing related step will occur, except for setting any required environment variables.
This is useful for testing and debugging purposes. Leaving this on in a CI environment would defeat the purpose of autodocs
Default: 'false'
FLAG_SKIP_PUSH
String (Environment Variable)
Set to false to do all of the steps in publishing, except for the final step of pushing the changes to the git remote.
This is useful for testing and debugging purposes. Leaving this on in a CI environment would defeat the purpose of autodocs
Default: 'false'
FLAG_SKIP_TEST
String (Environment Variable)
Set to true to skip step where documentation is tested. i.e. Do not run tests
npm run testdocs
This is useful when the generate command executes its own tests
Default: 'false'
FLAG_STRIP_TOKEN_OUTPUT
String (Environment Variable)
Any tokens contained in the build output will be stripped out before being printed. This is to ensure security, especially if your CI's build logs are publicly available
Default: 'true'
GIT_EMAIL
String (Environment Variable)
Email address to use when creating the Git commit
Default: 'autodocs-git-user@bguiz.com'
GIT_USER
String (Environment Variable)
Name to use when creating the Git commit
Default: 'autodocs Git User'
MAJOR_VERSION
String (Environment Variable)
The major version of the project.
1.2.3
--> 1
Default: The major version read in from package.json
MINOR_VERSION
String (Environment Variable)
The minor version of the project
1.2.3
--> 2
Default: The minor version read in from package.json
PATCH_VERSION
String (Environment Variable)
The patch version of the project
1.2.3
--> 3
Default: The patch version read in from package.json
PROJECT_DIR
String (Environment Variable)
The directory that the project being published ios located in.
Default: The current working directory
SELECT_CI
String (Environment Variable)
Default: 'travis'
SELECT_PUBLISH
String (Environment Variable)
Default: 'github-pages'