docat-org/docat

Host your docs. Simple. Versioned. Fancy.

Host your docs. Simple. Versioned. Fancy.

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:

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

docat's Issues

Creo que te equivocas en el archivo 10

Adding latest version should not create a new version

I have uploaded 2 versions:
2.0 and 2.1

Then I used this command to mark 2.1 as latest:
curl -X PUT http://docs.company.com/api/LabCore%20File%20Handling/2.1/tags/latest

This created a 3rd entry called "latest", which is fine, but in fact "latest" is a duplicated of "2.1".
2.1 version should just be marked as "latest"

Docs can be overwritten

One should not be able to overwrite docs

Edit metadata of project

Add some metadata of a project for example:

• email
• mainatainer
• git url
• logo image

Update Dockerfile to use something like uwsgi

We should not use the flask dev server:

WARNING: This is a development server. Do not use it in a production deployment.

Consider:

• uwsgi
• gunicorn
• or similar

Add automated tests

\There are currently no automated tests ... It's cumbersome to test if stuff is working manually. In addition I can only guess the expected behavior or features in general.

Documentation makes usage confusing

On the help/readme page there is always http://localhost:8000 shown. This should be dynamic especialy when hosted somewhere
so users can just copy paste the examples and are not confused by host and port not matching the actual instance.

Implement search

Add a global search functionality for:

• projects
• doc content

Documentation on how to prevent anyone from uploading files

This may be already solved, or considered trivial by more experienced people, but I just want to host documentation for a project of mine.

If I now host my Docat website and link to a project, any user could click the home icon:

and then upload anything, since that does not require a token of any sort, if the version name is different:

besides this being a possible security risk I also don't want anyone to be able to upload files.

Otherwise, anyone would also be able to upload files using curl:

curl -X POST -F "[email protected]" http://localhost:8000/api/existing-project/none-existing-version

Either there is some obvious difference between my localhost website and a public one, but if anyone can also upload files from anywhere, I think this should be solved?

Add 'upload your docs here' page

Simple page for 'noobs' where you can just drop a zip file and the docs will be upladed (and taged latest)

Only file index.html is rendered as html

If I upload a single html file not called index.html, it won't be rendered as html. If you require this behavior, please state so in the help.

Unable to stop docker container with SIGINT

I cannot stop the docker container from running with Ctrl+C - I think that should always be possible :)

strip extra slash on versions

If you add a extra slash at the end to post a version like this it fails with 404 without message on curl:

curl -X POST -F "file=@_site.zip" http://docs.company.com/api/project/2.0.0/

this one will work:

curl -X POST -F "file=@_site.zip" http://docs.company.com/api/project/2.0.0

Don't list tags as versions

Frontend: Implement claim token

Currently its not possible to claim a project from the frontend.

Let a user favor projects

Add a client-side-only (local storage, cookie based, ...) doc favoring system.
The docs I've favored should show up in the first row, separated from the other docs being displayed more towards the bottom of the page.

Participation in Hacktoberfest 2021?

Not an issue, but more of a suggestion - what do you guys think about including this project for Hacktoberfest 2021?

Contributors could pitch in with their contributions for open issues and I think this project needs more exposure and adoption.

Cheers!

Unable to upload files

Whenever I try to upload a file using the commands shown in the docatl help menu, I get the following error.
docatl --host http://localhost push ~/docs/gravity.zip myproject 1.0.0 -t latest
I recive the error, unable to upload documentation: (status code: 404)

Uploaded pdf documents are not opened

Uploading a pdf document will not be shown directly. First, a page is shown that a pdf document exists.

[
{ "name":"design-lib.pdf", "type":"file", "mtime":"Tue, 02 Feb 2021 16:45:06 GMT", "size":1139382 }
]

You have to add the document to the url yourself (http://docs.company.com/#/project-lib/8.0.0/design-lib.pdf), open that page and hit refresh because it is not opened the first time with that url.

s3 backend

allow serving/proxying docs from s3.

I would like to give this shot or if someone else wants a crack at it we can work together on this.

What do ya think about this feature?

@randombenj @timofurrer @fliiiix

Handle 'latest' tag not as a version rather combine it like 1.2.3 (latest)'

Hi guys
I would like to see the 'latest' tag behind the actual version.
Right now it looks like latest is a custom version.

Remove axios and use fetch

Make Corporate design

DOCAT will need a Corporate design, with logo etc...

Okay

Add API or UI to set project icon

Add an API and/or UI to set or change the icon of a project.

Improve http response when uploads fail due to broken tagged version

We encountered this on an internal deployment, but wanted to post a related bug report here for tracking.

We were trying to deploy to a tag that was "broken" (still not entirely sure what that means), and got the response

$ curl --request POST \
       --header "Docat-Api-Key: $TOKEN" \
       --form "[email protected]" \
       "http://www.mydocat.com/api/myproj/brokentag"

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<title>500 Internal Server Error</title>
<h1>Internal Server Error</h1>
<p>The server encountered an internal error and was unable to complete your request. Either the server is overloaded or there is an error in the application.</p>

If it's possible to identify a broken tag, would it be possible to include response content that indicates that the issue is with the existing site contents for that tag?

Add a Docat API client/CLI tool

API endpoints are hard to remember and hard to read.
A nice-to-have feature would be a Docat API client, which can be used with Python or with the command line.

The Docat CLI tool shall be runnable via a Docker container or via Pip

e.g.
Tag:

# Previously:
$ curl -X PUT http://localhost:8000/api/PROJECT/VERSION/tags/latest
# After:
$ docat tag my-project 1.0.0 latest --url http://localhost:8000

Publish:

# Previously:
$ curl -X POST -F "[email protected]" http://localhost:8000/api/PROJECT/VERSION
# After:
$ docat push my-project 1.0.0 ./docs.zip --url http://localhost:8000

(optional) Add a docat.yml config:

$ cat <<EOF > docat.yml
url: http://localhost:8000
project: my-project
EOF

$ docat push 1.0.0 ./docs.zip

or as API client

from docat import tag

tag("my-project", "1.0.0", "latest")

Add a cli tool

Add a small cli tool to push documentation to the server could be something like:

docli push [DIR] [-version VERSION -project PROJECT -tag TAG]

New ProjectVersion breaks version comparing

Hi,

I might be wrong, but could it be that the #239 PR broke the selection of the latest version at multiple places?

I discovered this when clicking on a project in the latest release and realizing that I'm on a very old version :)

If I understood it correctly, the data structure being sent won't contain a version with the name latest anymore. Instead, a tags property contains this information.

{
    "name": "my-project",
    "versions": [
        {
            "name": "1.9",
            "tags": []
        },
        {
            "name": "1.15",
            "tags": [
                "latest"
            ]
        }
     ]
}

However, Project.vue for example still does the searching for the latest version based on the name:

this.latestVersion = (this.versions.find((version) => version.name == 'latest') || this.versions[0]).name

Without diving deeper, it looks like same goes for Docs.vue.

If I get some time soon, I will try to fix this. I think it would be great to get rid of this bug soon, since it probably affects many projects.

[Feature Request] Option to hide version dropdown menu and link directly to specific tag site

Sometimes it's nice to link users to documentation without the option to bounce between versions. Especially if the production version of a product isn't on the latest release, users might see the version option and want to jump to the latest release assuming it is the deployed version but see docs that are out-of-sync with their use.

In this scenario, it would be helpful to be able to link to a specific version without the option to switch.

For example, perhaps mydocat.com/project/tag links to the docs with the version switching ui, but mydocat.com/project/tag?hideui=1 just displays the raw documentation page, or the page with docat header, but no version toggle.

Move docat to an org

lets talk about this @randombenj

Allow to configure the prefix path

I tried to configure docat after my other Nginx server where Jenkins is running. The root path of the server is reserved also.

It would be great to allow to set somewhere the prefix path of the app so it would be possible to use it from a different path:

myserver/docat/#
myserver/docat/doc/myproject/latest

The backend works without issue, but the web interface has troubles dealing with that. You can enable part of the frontend by rebuilding the container while modifying the vue.config.js to contain publicPath: '/docat/' but that does not make it entirely work.

Add project name in docs overview

Right now you can not see at which project you are looking at in the docs page.

Version is not reloaded

Pass in the version
https://github.com/randombenj/docat/blob/master/web/src/pages/Docs.vue#L7

Token documentation

Document in UI and Docs that after getting the token there is no way to get it again so one should take care and store it safely.

Projects can not be renamed

I often publish a document with the wrong name or want to rename it because I have a similar document to clarify the differences. Therefore, an option to rename an existing document/project would be nice.

[Bug] Cannot build the docker : error with JS

I've been trying to build the docker image myself. The doc can be viewed but the pages uploads, claim and delete don't display.
No errors on python or nginx side, but the console returns the following error: "SyntaxError: Unexpected token < in JSON at position 0" in vue.runtime.esm.js:1897

Change page title according to open documentation

It would be nice if the docat page would change it's title (as in <title>) - and maybe even the favicon - according the the currently open documentation.

The title could e.g. include the project name and version - maybe also with | docat as a suffix.

Create docker image

Simple upload page doesn't work

Hello!

yesterday I stumbled over this project and this is exactly what I need, very cool!
Everything works fine so far, except the upload page. I'm not sure if I'm doing something wrong.
Tested in different browsers, always the same result.

I use the latest "unstable" docker container "aac8d43c91a2".

Problem description:
In the moment I choose the file to upload in the file selected I get an error in the browser console:
this.$el.validity is undefined

If I click upload afterwards, nothing in the browser UI happens except resetting all fields.
The docat server responds with "No file part in the request" in the browser console.

Uploading the same file via curl always works fine.

UX Upload documentation

The UI/UX could be better here, with where the input fields are.

Add screenshots of the pages

Frontend: implement delete version

Needs #107.
Allow to delete a version from frontend.

Sort versions (newest version first)

Versions are sorted in the wrong order. This should be changed

Allow to hide versions in dropdown

I would like to hide versions in the headers dropdown menu via the docat API

Use cases:

• Versions which only get deployed for internal purposes (e.g. for reviews)
• Keeping version links live, but making it accessible via the user interface

Sub-site URLs don't work

1. Navigate to a DOCAT sub-site (Project+version)
2. Copy and paste the url to a new tab
3. You see the proper page for a moment, but then you are redirected to the main sub-site.

Reduce visual weight of docat layout overlayed on docs

Thanks for the awesome work @randombenj

On most displays, vertical space is a commodity. Having a floating header overlayed on the docs page can take up a considerable amount of space (especially on lower resolution displays) for what amounts to just a dropdown menu. Many docs pages themselves have their own headerbar, so this space gets eaten up quickly. I imagine that switching between docs versions usually only needs to happen once for most people browsing documentation, so it seems like a lot of space devoted to what should be an uncommon action.

Web design and ui/ux are not my usual focus, but some ideas that jump to mind to regain some of this space:

• Reduce the height (a rough draft experimenting with a super condensed version)
  
• Consider keeping the menu bar in an absolute position so that it doesn't consume space while scrolling through docs
• Perhaps a floating docat icon that can be clicked to expand a menu that includes the dropdown
• A (collapsible?) sidebar (another mock-up of a super condensed left panel)
  
• Interpret a url parameter to hide the header entirely (especially useful for linking users to a specific version, where other versions would be irrelevant, but maybe this is a separate request).

Minimize the docker image

I think 300 MB is a bit much for such a small app :)

Host a demo somewhere

Host a demo site, where you can see what docat is able to do live!
If we want to do this we may also have to implement some very simple authentication
(maybe with a token or something like that).

Add ability to delete docs

Implement something like DELETE /api/PROJECT/VERSION