Skip to content

Host your docs. Simple. Versioned. Fancy.

License

Notifications You must be signed in to change notification settings

vorausrobotik/docat

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

docat

Host your docs. Simple. Versioned. Fancy.

build Gitter

Getting started

The simplest way is to build and run the docker container, you can optionally use volumes to persist state:

# run container in background and persist data (docs, nginx configs and tokens database)
# use 'ghcr.io/docat-org/docat:unstable' to get the latest changes
mkdir -p docat-run/doc
docker run \
  --detach \
  --volume $PWD/docat-run:/var/docat/ \
  --publish 8000:80 \
  ghcr.io/docat-org/docat

Go to localhost:8000 to view your docat instance:

docat screenshot

Local Development

For local development, first configure and start the backend (inside the docat/ folder):

# create a folder for local development (uploading docs)
DEV_DOCAT_PATH="$(mktemp -d)"

# install dependencies
poetry install

# run the local development version
DOCAT_SERVE_FILES=1 DOCAT_STORAGE_PATH="$DEV_DOCAT_PATH" poetry run python -m docat

After this you need to start the frontend (inside the web/ folder):

# install dependencies
yarn install --frozen-lockfile

# run the web app
yarn serve

For more advanced options, have a look at the backend and web docs.

Push Documentation to docat

The preferred way to push documentation to a docat server is using the docatl command line application:

docatl push --host http://localhost:8000 /path/to/your/docs PROJECT VERSION

There are also docker images available for CI systems.

Using Standard UNIX Command Line Tools

If you have static html documentation or use something like mkdocs, sphinx, ... to generate your documentation, you can push it to docat:

# create a zip of your docs
zip -r docs.zip /path/to/your-docs
# upload them to the docat server (replace PROJECT/VERSION with your projectname and the version of the docs)
curl -X POST -F "[email protected]" http://localhost:8000/api/PROJECT/VERSION

When you have multiple versions you may want to tag some version as latest:

# tag the version VERSION of project PROJECT as latest
curl -X PUT http://localhost:8000/api/PROJECT/VERSION/tags/latest

Same thing with docatl:

# tag the version VERSION of project PROJECT as latest
docatl tag --host http://localhost:8000 PROJECT VERSION latest

Advanced Frontend config.json

It is possible to configure some things after the fact.

  1. Create a config.json file
  2. Mount it inside your docker container --volume /path/to/config.json:/var/www/html/config.json

Supported config options:

  • headerHTML

Advanced System Config

Further proxy configurations can be done through the following environmental variables:

Varaiable Default (Link to Definition) Description
MAX_UPLOAD_SIZE 100M Limits the size of individual archives posted to the API

About

Host your docs. Simple. Versioned. Fancy.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 43.8%
  • Python 37.4%
  • CSS 17.6%
  • Other 1.2%