Welcome to Docinator! Docinator extracts documentation in the form of PlantUML diagrams, Swagger specs, markdowns, and more to build a beautiful documentation website without any modifications to your repository. Docinator "just works" - install it, run it, that's it.
Learn to use Docinator by reading the user documentation or simply run docinator --help
command.
Any editor will do, but effort has been put into getting VSCode configured just right so please use that unless you have a strong preference for another editor.
You'll need Java 8 or above for the PlantUML integration.
The following will download the code, install dependencies, and serve the Docinator documentation:
git clone --recurse-submodules [email protected]:tmobile/docinator.git
cd docinator
npm i
ts-node src/cli.ts serve
npm run build && npm link
docinator --help
Docinator will now be available on the command line.
To avoid having to re-link between changes, use ts-node:
ts-node src/cli.ts --help
docker build -t docinator .
To build a Docinator site:
docker run -v "$(pwd):/data" -ti docinator build
To serve a Docinator site:
docker run -v "$(pwd):/data" -p 1313:1313 -ti docinator serve
Note about using
$(pwd)
on Docker for Windows using GitBash and WSL-based engine: The$(pwd)
value will pass the Windows path to the Linux host where it is invalid. Instead, try running directly from a WSL terminal
Note about WSL: WSL may not allow port access on
1313
by default. Usesudo ufw allow 1313
to allow access to port1313
. You can disallow this later withsudo ufw deny 1313
.
Heads up: changes to the Hugo template need a rebuild of the Docker image...
- Hugo and Hugo Theme Learn are used to generate static websites.
- PlantUML is used to generate PlantUML diagrams; this repository includes a binary distribution of PlantUML.
- Swagger UI is used to visualize swagger files.
- Additional libraries and frameworks used are listed in the package.json file of this repository.