### Using DOCAT
> 🛈 Please note that docat does not provide any way to write documentation.
> It's sole responsibility is to host documentation.
>
> There are many awesome tools to write documenation:
> - [mkdocs](https://www.mkdocs.org/)
> - [sphinx](http://www.sphinx-doc.org/en/master/)
> - [mdbook](https://rust-lang.github.io/mdBook/)
> - ...
A CLI tool called [docatl](https://github.com/docat-org/docatl) is available
for easy interaction with the docat server.
However, interacting with docat can also be done through [`curl`](doc/getting-started.md).
To push documentation (and tag as `latest`) in the folder `docs/` simply run:
```sh
docatl push --host http://localhost:8000 ./docs PROJECT VERSION --tag latest
```
More detailed instructions can be found in the [**getting started guide**](doc/getting-started.md).
## Authentication
By default, anyone can upload new documentation or add a new version to documentation.
A project can be claimed. A claim returns a token that then must be used
to add or delete versions.
When hosting docat publicly, it is recommended to use
[http basic auth](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/)
for all `POST`/`PUT` and `DELETE` http calls.
Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # check detected before hiding project_details_response = client_with_claimed_project.get("/api/projects/some-project") assert project_details_response.status_code == 200 assert project_details_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], } # hide the version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # check hidden project_details_response = client_with_claimed_project.get("/api/projects/some-project") assert project_details_response.status_code == 200 assert project_details_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [], } @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_hide_only_version_not_listed_in_projects(_, client_with_claimed_project): """ Test that the project is not listed in the projects endpoint when the only version is hidden """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # check detected before hiding projects_response = client_with_claimed_project.get("/api/projects") assert projects_response.status_code == 200 assert projects_response.json() == { "projects": [ { "name": "some-project", "logo": False, "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], } ], } # hide the only version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # check hidden projects_response = client_with_claimed_project.get("/api/projects") assert projects_response.status_code == 200 assert projects_response.json() == { "projects": [], } # check versions hidden project_details_response = client_with_claimed_project.get("/api/projects/some-project") assert project_details_response.status_code == 200 assert project_details_response.json() == {"name": "some-project", "storage": "20 bytes", "versions": []} def test_hide_creates_hidden_file(client_with_claimed_project): """ Tests that the hidden file is created when hiding a version """ hidden_file_path = docat.DOCAT_UPLOAD_FOLDER / "some-project" / "1.0.0" / ".hidden" # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # check open was called at least once with the correct path with patch("docat.app.open") as open_file_mock: # hide hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} open_file_mock.assert_called_once_with(hidden_file_path, "w") def test_hide_fails_project_does_not_exist(client_with_claimed_project): """ Tests that hiding a version fails when the project does not exist """ with patch("docat.app.open") as open_file_mock: hide_response = client_with_claimed_project.post("/api/does-not-exist/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 404 assert hide_response.json() == {"message": "Project does-not-exist not found"} open_file_mock.assert_not_called() def test_hide_fails_version_does_not_exist(client_with_claimed_project): """ Tests that hiding a version fails when the version does not exist """ with patch("docat.app.open") as open_file_mock: # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # hide different version hide_response = client_with_claimed_project.post("/api/some-project/2.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 404 assert hide_response.json() == {"message": "Version 2.0.0 not found"} open_file_mock.assert_not_called() def test_hide_fails_already_hidden(client_with_claimed_project): """ Tests that hiding a version fails when the version is already hidden """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # hide version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} with patch("docat.app.open") as open_file_mock: # hide version again hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 400 assert hide_response.json() == {"message": "Version 1.0.0 is already hidden"} open_file_mock.assert_not_called() def test_hide_fails_no_token(client_with_claimed_project): """ Tests that hiding a version fails when no token is provided """ with patch("docat.app.open") as open_file_mock: # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # hide version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide") assert hide_response.status_code == 401 assert hide_response.json() == {"message": "Please provide a header with a valid Docat-Api-Key token for some-project"} open_file_mock.assert_not_called() def test_hide_fails_invalid_token(client_with_claimed_project): """ Tests that hiding a version fails when an invalid token is provided """ with patch("docat.app.open") as open_file_mock: # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # hide version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "invalid"}) assert hide_response.status_code == 401 assert hide_response.json() == {"message": "Docat-Api-Key token is not valid for some-project"} open_file_mock.assert_not_called() @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_show(_, client_with_claimed_project): """ Tests that the version is no longer marked as hidden after requesting show. """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # hide the version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # check hidden project_details_response = client_with_claimed_project.get("/api/projects/some-project") assert project_details_response.status_code == 200 assert project_details_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [], } # show the version show_response = client_with_claimed_project.post("/api/some-project/1.0.0/show", headers={"Docat-Api-Key": "1234"}) assert show_response.status_code == 200 assert show_response.json() == {"message": "Version 1.0.0 is now shown"} # check detected again project_details_response = client_with_claimed_project.get("/api/projects/some-project") assert project_details_response.status_code == 200 assert project_details_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], } def test_show_deletes_hidden_file(client_with_claimed_project): """ Tests that the hidden file is deleted when requesting show. """ hidden_file_path = docat.DOCAT_UPLOAD_FOLDER / "some-project" / "1.0.0" / ".hidden" # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # hide the version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # check os.remove was called at least once with the correct path with patch("os.remove") as remove_file_mock: # show again show_response = client_with_claimed_project.post("/api/some-project/1.0.0/show", headers={"Docat-Api-Key": "1234"}) assert show_response.status_code == 200 assert show_response.json() == {"message": "Version 1.0.0 is now shown"} remove_file_mock.assert_called_once_with(hidden_file_path) def test_show_fails_project_does_not_exist(client_with_claimed_project): """ Tests that showing a version fails when the project does not exist """ with patch("os.remove") as delete_file_mock: show_response = client_with_claimed_project.post("/api/does-not-exist/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert show_response.status_code == 404 assert show_response.json() == {"message": "Project does-not-exist not found"} delete_file_mock.assert_not_called() def test_show_fails_version_does_not_exist(client_with_claimed_project): """ Tests that showing a version fails when the version does not exist """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # hide the version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} with patch("os.remove") as delete_file_mock: # show different version show_response = client_with_claimed_project.post("/api/some-project/2.0.0/show", headers={"Docat-Api-Key": "1234"}) assert show_response.status_code == 404 assert show_response.json() == {"message": "Version 2.0.0 not found"} delete_file_mock.assert_not_called() def test_show_fails_already_shown(client_with_claimed_project): """ Tests that showing a version fails when the version is already shown """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 with patch("os.remove") as delete_file_mock: # show version show_response = client_with_claimed_project.post("/api/some-project/1.0.0/show", headers={"Docat-Api-Key": "1234"}) assert show_response.status_code == 400 assert show_response.json() == {"message": "Version 1.0.0 is not hidden"} delete_file_mock.assert_not_called() def test_show_fails_no_token(client_with_claimed_project): """ Tests that showing a version fails when no token is provided """ with patch("os.remove") as remove_file_mock: # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # hide version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # try to show without token show_response = client_with_claimed_project.post("/api/some-project/1.0.0/show") assert show_response.status_code == 401 assert show_response.json() == {"message": "Please provide a header with a valid Docat-Api-Key token for some-project"} remove_file_mock.assert_not_called() def test_show_fails_invalid_token(client_with_claimed_project): """ Tests that showing a version fails when an invalid token is provided """ with patch("os.remove") as remove_file_mock: # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # hide version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # try to show without token show_response = client_with_claimed_project.post("/api/some-project/1.0.0/show", headers={"Docat-Api-Key": "invalid"}) assert show_response.status_code == 401 assert show_response.json() == {"message": "Docat-Api-Key token is not valid for some-project"} remove_file_mock.assert_not_called() @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_hide_and_show_with_tag(_, client_with_claimed_project): """ Tests that the version is no longer marked as hidden after requesting show on a tag. """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # create a tag create_tag_response = client_with_claimed_project.put("/api/some-project/1.0.0/tags/latest") assert create_tag_response.status_code == 201 assert create_tag_response.json() == {"message": "Tag latest -> 1.0.0 successfully created"} # hide the tag hide_response = client_with_claimed_project.post("/api/some-project/latest/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version latest is now hidden"} # check hidden project_details_response = client_with_claimed_project.get("/api/projects/some-project") assert project_details_response.status_code == 200 assert project_details_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [], } # show the version show_response = client_with_claimed_project.post("/api/some-project/latest/show", headers={"Docat-Api-Key": "1234"}) assert show_response.status_code == 200 assert show_response.json() == {"message": "Version latest is now shown"} # check detected again project_details_response = client_with_claimed_project.get("/api/projects/some-project") assert project_details_response.status_code == 200 assert project_details_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": ["latest"], "hidden": False}], } ================================================ FILE: docat/tests/test_project.py ================================================ import io from datetime import datetime from unittest.mock import patch import httpx from fastapi.testclient import TestClient import docat.app as docat from docat.models import ProjectDetail, ProjectVersion from docat.utils import get_project_details client = TestClient(docat.app) @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_project_api(_, temp_project_version): docs = temp_project_version("project", "1.0") docs = temp_project_version("different-project", "1.0") with patch("docat.app.DOCAT_UPLOAD_FOLDER", docs): response = client.get("/api/projects") assert response.status_code == httpx.codes.OK assert response.json() == { "projects": [ { "name": "different-project", "logo": False, "storage": "0 bytes", "versions": [ {"name": "1.0", "timestamp": "2000-01-01T01:01:00", "tags": ["latest"], "hidden": False}, ], }, { "name": "project", "logo": False, "storage": "0 bytes", "versions": [ {"name": "1.0", "timestamp": "2000-01-01T01:01:00", "tags": ["latest"], "hidden": False}, ], }, ] } def test_project_api_without_any_projects(): response = client.get("/api/projects") assert response.status_code == httpx.codes.OK assert response.json() == {"projects": []} @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_project_details_api(_, temp_project_version): project = "project" docs = temp_project_version(project, "1.0") symlink_to_latest = docs / project / "latest" assert symlink_to_latest.is_symlink() with patch("docat.app.DOCAT_UPLOAD_FOLDER", docs): response = client.get(f"/api/projects/{project}") assert response.status_code == httpx.codes.OK assert response.json() == { "name": "project", "storage": "0 bytes", "versions": [{"name": "1.0", "timestamp": "2000-01-01T01:01:00", "tags": ["latest"], "hidden": False}], } def test_project_details_api_with_a_project_that_does_not_exist(): response = client.get("/api/projects/i-do-not-exist") assert not response.status_code == httpx.codes.OK assert response.json() == {"message": "Project i-do-not-exist does not exist"} @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_get_project_details_with_hidden_versions(_, client_with_claimed_project): """ Make sure that get_project_details works when include_hidden is set to True. """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # check detected before hiding details = get_project_details(docat.DOCAT_UPLOAD_FOLDER, "some-project", include_hidden=True) assert details == ProjectDetail( name="some-project", storage="20 bytes", versions=[ProjectVersion(name="1.0.0", timestamp=datetime(2000, 1, 1, 1, 1, 0), tags=[], hidden=False)], ) # hide the version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # check hidden details = get_project_details(docat.DOCAT_UPLOAD_FOLDER, "some-project", include_hidden=True) assert details == ProjectDetail( name="some-project", storage="20 bytes", versions=[ProjectVersion(name="1.0.0", timestamp=datetime(2000, 1, 1, 1, 1, 0), tags=[], hidden=True)], ) @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_project_details_without_hidden_versions(_, client_with_claimed_project): """ Make sure that project_details works when include_hidden is set to False. """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # check detected before hiding details = get_project_details(docat.DOCAT_UPLOAD_FOLDER, "some-project", include_hidden=False) assert details == ProjectDetail( name="some-project", storage="20 bytes", versions=[ProjectVersion(name="1.0.0", timestamp=datetime(2000, 1, 1, 1, 1, 0), tags=[], hidden=False)], ) # hide the version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # check hidden details = get_project_details(docat.DOCAT_UPLOAD_FOLDER, "some-project", include_hidden=False) assert details == ProjectDetail(name="some-project", storage="20 bytes", versions=[]) @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_include_hidden_parameter_for_get_projects(_, client_with_claimed_project): """ Make sure that include_hidden has the desired effect on the /api/projects endpoint. """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # check detected before hiding get_projects_response = client_with_claimed_project.get("/api/projects") assert get_projects_response.status_code == 200 assert get_projects_response.json() == { "projects": [ { "name": "some-project", "logo": False, "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], } ] } # check include_hidden=True get_projects_response = client_with_claimed_project.get("/api/projects?include_hidden=true") assert get_projects_response.status_code == 200 assert get_projects_response.json() == { "projects": [ { "name": "some-project", "logo": False, "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], } ] } # hide the version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # check include_hidden=False get_projects_response = client_with_claimed_project.get("/api/projects?include_hidden=false") assert get_projects_response.status_code == 200 assert get_projects_response.json() == {"projects": []} # check include_hidden=True get_projects_response = client_with_claimed_project.get("/api/projects?include_hidden=true") assert get_projects_response.status_code == 200 assert get_projects_response.json() == { "projects": [ { "name": "some-project", "logo": False, "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": True}], } ] } @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_include_hidden_parameter_for_get_project_details(_, client_with_claimed_project): """ Make sure that include_hidden has the desired effect on the /api/project/{project} endpoint. """ # create a version create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # check detected before hiding get_projects_response = client_with_claimed_project.get("/api/projects/some-project") assert get_projects_response.status_code == 200 assert get_projects_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], } # check include_hidden=True get_projects_response = client_with_claimed_project.get("/api/projects/some-project?include_hidden=true") assert get_projects_response.status_code == 200 assert get_projects_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], } # hide the version hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) assert hide_response.status_code == 200 assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} # check include_hidden=False get_projects_response = client_with_claimed_project.get("/api/projects/some-project?include_hidden=false") assert get_projects_response.status_code == 200 assert get_projects_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [], } # check include_hidden=True get_projects_response = client_with_claimed_project.get("/api/projects/some-project?include_hidden=true") assert get_projects_response.status_code == 200 assert get_projects_response.json() == { "name": "some-project", "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": True}], } ================================================ FILE: docat/tests/test_rename.py ================================================ import io from pathlib import Path from unittest.mock import call, patch from tinydb import Query import docat.app as docat def test_rename_fail_project_does_not_exist(client_with_claimed_project): with patch("os.rename") as rename_mock: response = client_with_claimed_project.put("/api/does-not-exist/rename/new-project-name") assert response.status_code == 404 assert response.json() == {"message": "Project does-not-exist not found"} assert rename_mock.mock_calls == [] def test_rename_fail_new_project_name_already_used(client_with_claimed_project): with patch("os.rename") as rename_mock: create_first_project_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_first_project_response.status_code == 201 create_second_project_response = client_with_claimed_project.post( "/api/second-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_second_project_response.status_code == 201 rename_response = client_with_claimed_project.put("/api/some-project/rename/second-project") assert rename_response.status_code == 409 assert rename_response.json() == {"message": "New project name second-project already in use"} assert rename_mock.mock_calls == [] def test_rename_not_authenticated(client_with_claimed_project): with patch("os.rename") as rename_mock: create_project_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}, ) assert create_project_response.status_code == 201 rename_response = client_with_claimed_project.put("/api/some-project/rename/new-project-name") assert rename_response.status_code == 401 assert rename_response.json() == {"message": "Please provide a header with a valid Docat-Api-Key token for some-project"} assert rename_mock.mock_calls == [] def test_rename_success(client_with_claimed_project): with patch("os.rename") as rename_mock: create_project_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}, ) assert create_project_response.status_code == 201 rename_response = client_with_claimed_project.put("/api/some-project/rename/new-project-name", headers={"Docat-Api-Key": "1234"}) assert rename_response.status_code == 200 assert rename_response.json() == {"message": "Successfully renamed project some-project to new-project-name"} old_path = docat.DOCAT_UPLOAD_FOLDER / Path("some-project") new_path = docat.DOCAT_UPLOAD_FOLDER / Path("new-project-name") assert rename_mock.mock_calls == [call(old_path, new_path)] Project = Query() table = docat.db.table("claims") claims_with_old_name = table.search(Project.name == "some-project") assert len(claims_with_old_name) == 0 claims_with_new_name = table.search(Project.name == "new-project-name") assert len(claims_with_new_name) == 1 def test_rename_rejects_forbidden_project_name(client_with_claimed_project): """ Names that conflict with pages in docat web are forbidden, and renaming a project to such a name should fail. """ create_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 with patch("os.rename") as rename_mock: for project_name in ["upload", "claim", "Delete ", "help", "Doc", "API"]: rename_response = client_with_claimed_project.put(f"/api/some-project/rename/{project_name}", headers={"Docat-Api-Key": "1234"}) assert rename_response.status_code == 400 assert rename_response.json() == { "message": f'New project name "{project_name}" is forbidden, as it conflicts with pages in docat web.' } assert rename_mock.mock_calls == [] ================================================ FILE: docat/tests/test_stats.py ================================================ import io from datetime import datetime from unittest.mock import patch import pytest @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) @pytest.mark.parametrize( ("project_config", "n_projects", "n_versions", "storage"), [ ([("some-project", ["1.0.0"])], 1, 1, "20 bytes"), ([("some-project", ["1.0.0", "2.0.0"])], 1, 2, "40 bytes"), ([("some-project", ["1.0.0", "2.0.0"])], 1, 2, "40 bytes"), ([("some-project", ["1.0.0", "2.0.0"]), ("another-project", ["1"])], 2, 3, "60 bytes"), ], ) def test_get_stats(_, project_config, n_projects, n_versions, storage, client_with_claimed_project): """ Make sure that get_stats works. """ # create a version for project_name, versions in project_config: for version in versions: create_response = client_with_claimed_project.post( f"/api/{project_name}/{version}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_response.status_code == 201 # get system stats hide_response = client_with_claimed_project.get("/api/stats") assert hide_response.status_code == 200 assert hide_response.json() == {"n_projects": n_projects, "n_versions": n_versions, "storage": storage} ================================================ FILE: docat/tests/test_upload.py ================================================ import io from pathlib import Path from unittest.mock import call, patch import docat.app as docat def test_successfully_upload(client): with patch("docat.app.remove_docs"): response = client.post("/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}) response_data = response.json() assert response.status_code == 201 assert response_data["message"] == "Documentation uploaded successfully" assert (docat.DOCAT_UPLOAD_FOLDER / "some-project" / "1.0.0" / "index.html").exists() def test_successfully_override(client_with_claimed_project): with patch("docat.app.remove_docs") as remove_mock: response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert response.status_code == 201 response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}, headers={"Docat-Api-Key": "1234"}, ) response_data = response.json() assert response.status_code == 201 assert response_data["message"] == "Documentation uploaded successfully" assert remove_mock.mock_calls == [call("some-project", "1.0.0", docat.DOCAT_UPLOAD_FOLDER)] def test_tags_are_not_overwritten_without_api_key(client_with_claimed_project): with patch("docat.app.remove_docs") as remove_mock: response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert response.status_code == 201 response = client_with_claimed_project.put("/api/some-project/1.0.0/tags/latest") assert response.status_code == 201 response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) response_data = response.json() assert response.status_code == 401 assert response_data["message"] == "Please provide a header with a valid Docat-Api-Key token for some-project" assert remove_mock.mock_calls == [] def test_successful_tag_creation(client_with_claimed_project): with patch("docat.app.create_symlink") as create_symlink_mock: create_project_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_project_response.status_code == 201 create_tag_response = client_with_claimed_project.put("/api/some-project/1.0.0/tags/latest") assert create_tag_response.status_code == 201 assert create_tag_response.json() == {"message": "Tag latest -> 1.0.0 successfully created"} destination_path = docat.DOCAT_UPLOAD_FOLDER / Path("some-project") / Path("latest") assert create_symlink_mock.mock_calls == [call("1.0.0", destination_path), call().__bool__()] def test_create_tag_fails_when_version_does_not_exist(client_with_claimed_project): with patch("docat.app.create_symlink") as create_symlink_mock: create_project_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_project_response.status_code == 201 create_tag_response = client_with_claimed_project.put("/api/some-project/non-existing-version/tags/new-tag") assert create_tag_response.status_code == 404 assert create_tag_response.json() == {"message": "Version non-existing-version not found"} assert create_symlink_mock.mock_calls == [] def test_create_tag_fails_on_overwrite_of_version(client_with_claimed_project): """ Create a tag with the same name as a version. """ project_name = "some-project" version = "1.0.0" tag = "latest" create_first_project_response = client_with_claimed_project.post( f"/api/{project_name}/{version}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_first_project_response.status_code == 201 create_second_project_response = client_with_claimed_project.post( f"/api/{project_name}/{tag}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_second_project_response.status_code == 201 create_tag_response = client_with_claimed_project.put(f"/api/{project_name}/{version}/tags/{tag}") assert create_tag_response.status_code == 409 assert create_tag_response.json() == {"message": f"Tag {tag} would overwrite an existing version!"} def test_create_fails_on_overwrite_of_tag(client_with_claimed_project): """ Create a version with the same name as a tag. """ project_name = "some-project" version = "1.0.0" tag = "some-tag" create_project_response = client_with_claimed_project.post( f"/api/{project_name}/{version}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_project_response.status_code == 201 create_tag_response = client_with_claimed_project.put(f"/api/{project_name}/{version}/tags/{tag}") assert create_tag_response.status_code == 201 assert create_tag_response.json() == {"message": f"Tag {tag} -> {version} successfully created"} create_project_with_name_of_tag_response = client_with_claimed_project.post( f"/api/{project_name}/{tag}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert create_project_with_name_of_tag_response.status_code == 409 assert create_project_with_name_of_tag_response.json() == {"message": "Cannot overwrite existing tag with new version."} def test_fails_with_invalid_token(client_with_claimed_project): with patch("docat.app.remove_docs") as remove_mock: response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert response.status_code == 201 response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}, headers={"Docat-Api-Key": "456"}, ) response_data = response.json() assert response.status_code == 401 assert response_data["message"] == "Docat-Api-Key token is not valid for some-project" assert remove_mock.mock_calls == [] def test_upload_rejects_forbidden_project_name(client_with_claimed_project): """ Names that conflict with pages in docat web are forbidden, and creating a project with such a name should fail. """ with patch("docat.app.remove_docs") as remove_mock: for project_name in ["upload", "claim", " Delete ", "help", "DOC", "api"]: response = client_with_claimed_project.post( f"/api/{project_name}/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert response.status_code == 400 assert response.json() == {"message": f'Project name "{project_name}" is forbidden, as it conflicts with pages in docat web.'} assert remove_mock.mock_calls == [] def test_upload_issues_warning_missing_index_file(client_with_claimed_project): """ When a project is uploaded without an index.html file, a warning should be issued, but the upload should succeed. """ response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("some-other-file.html", io.BytesIO(b"Hello World
"), "plain/text")} ) response_data = response.json() assert response.status_code == 201 assert response_data["message"] == "Documentation uploaded successfully, but no index.html found at root of archive." assert (docat.DOCAT_UPLOAD_FOLDER / "some-project" / "1.0.0" / "some-other-file.html").exists() assert not (docat.DOCAT_UPLOAD_FOLDER / "some-project" / "1.0.0" / "index.html").exists() ================================================ FILE: docat/tests/test_upload_icon.py ================================================ import base64 import io from datetime import datetime from unittest.mock import call, patch import docat.app as docat ONE_PIXEL_PNG = base64.decodebytes( b"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAA1JREFUGFdjYGBg+A8AAQQBAHAgZQsAAAAASUVORK5CYII=" ) def test_successful_icon_upload(client_with_claimed_project): upload_folder_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert upload_folder_response.status_code == 201 with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: upload_response = client_with_claimed_project.post( "/api/some-project/icon", files={"file": ("icon.jpg", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, ) assert upload_response.status_code == 200 assert upload_response.json() == {"message": "Icon successfully uploaded"} assert remove_file_mock.mock_calls == [] assert len(copyfileobj_mock.mock_calls) == 1 def test_icon_upload_fails_with_no_project(client_with_claimed_project): with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: upload_response = client_with_claimed_project.post( "/api/non-existing-project/icon", files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, ) assert upload_response.status_code == 404 assert upload_response.json() == {"message": "Project non-existing-project not found"} assert remove_file_mock.mock_calls == [] assert copyfileobj_mock.mock_calls == [] def test_icon_upload_fails_no_token_and_existing_icon(client): """ upload twice, first time should be successful (nothing replaced), second time should fail (would need token to replace) """ upload_folder_response = client.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert upload_folder_response.status_code == 201 with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: upload_response_1 = client.post( "/api/some-project/icon", files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, ) assert upload_response_1.status_code == 200 assert upload_response_1.json() == {"message": "Icon successfully uploaded"} assert remove_file_mock.mock_calls == [] assert len(copyfileobj_mock.mock_calls) == 1 with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: upload_response_2 = client.post( "/api/some-project/icon", files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, ) assert upload_response_2.status_code == 401 assert upload_response_2.json() == {"message": "Please provide a header with a valid Docat-Api-Key token for some-project"} assert remove_file_mock.mock_calls == [] assert len(copyfileobj_mock.mock_calls) == 0 def test_icon_upload_successful_replacement_with_token(client_with_claimed_project): """ upload twice, both times should be successful (token provided) """ icon_path = docat.DOCAT_UPLOAD_FOLDER / "some-project" / "logo" upload_folder_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert upload_folder_response.status_code == 201 with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: upload_response_1 = client_with_claimed_project.post( "/api/some-project/icon", files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, headers={"Docat-Api-Key": "1234"}, ) assert upload_response_1.status_code == 200 assert upload_response_1.json() == {"message": "Icon successfully uploaded"} assert remove_file_mock.mock_calls == [] assert len(copyfileobj_mock.mock_calls) == 1 with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: upload_response_1 = client_with_claimed_project.post( "/api/some-project/icon", files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, headers={"Docat-Api-Key": "1234"}, ) assert upload_response_1.status_code == 200 assert upload_response_1.json() == {"message": "Icon successfully uploaded"} assert remove_file_mock.mock_calls == [call(icon_path)] assert len(copyfileobj_mock.mock_calls) == 1 def test_icon_upload_successful_no_token_no_existing_icon(client): upload_folder_response = client.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert upload_folder_response.status_code == 201 with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: upload_response = client.post( "/api/some-project/icon", files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, ) assert upload_response.status_code == 200 assert upload_response.json() == {"message": "Icon successfully uploaded"} assert remove_file_mock.mock_calls == [] assert len(copyfileobj_mock.mock_calls) == 1 def test_icon_upload_fails_no_image(client_with_claimed_project): upload_folder_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert upload_folder_response.status_code == 201 with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: upload_response = client_with_claimed_project.post( "/api/some-project/icon", files={"file": ("file.zip", io.BytesIO(b"not image data"), "application/zip")}, ) assert upload_response.status_code == 400 assert upload_response.json() == {"message": "Icon must be an image"} assert remove_file_mock.mock_calls == [] assert copyfileobj_mock.mock_calls == [] @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) def test_get_project_recongizes_icon(_, client_with_claimed_project): """ get_projects should return true, if the project has an icon """ upload_folder_response = client_with_claimed_project.post( "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} ) assert upload_folder_response.status_code == 201 projects_response = client_with_claimed_project.get("/api/projects") assert projects_response.status_code == 200 assert projects_response.json() == { "projects": [ { "name": "some-project", "logo": False, "storage": "20 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], } ] } upload_response = client_with_claimed_project.post( "/api/some-project/icon", files={"file": ("icon.jpg", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, ) assert upload_response.status_code == 200 projects_response = client_with_claimed_project.get("/api/projects") assert projects_response.status_code == 200 assert projects_response.json() == { "projects": [ { "name": "some-project", "logo": True, "storage": "103 bytes", "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], } ] } ================================================ FILE: docat/tests/test_utils.py ================================================ from pathlib import Path from unittest.mock import MagicMock, patch import docat.app as docat from docat.utils import create_symlink, extract_archive, get_dir_size, remove_docs def test_symlink_creation(): """ Tests the creation of a symlink """ source = MagicMock() destination = MagicMock() destination.exists.return_value = False destination.symlink_to.return_value = MagicMock() assert create_symlink(source, destination) destination.symlink_to.assert_called_once_with(source) def test_symlink_creation_overwrite_destination(): """ Tests the creation of a symlink and overwriting of existing symlink """ source = MagicMock() destination = MagicMock() destination.exists.return_value = True destination.is_symlink.return_value = True destination.unlink.return_value = MagicMock() destination.symlink_to.return_value = MagicMock() assert create_symlink(source, destination) destination.unlink.assert_called_once() destination.symlink_to.assert_called_once_with(source) def test_symlink_creation_do_not_overwrite_destination(): """ Tests wether a symlinc is not created when it would overwrite an existing version """ source = MagicMock() destination = MagicMock() destination.exists.return_value = True destination.is_symlink.return_value = False destination.unlink.return_value = MagicMock() destination.symlink_to.return_value = MagicMock() assert not create_symlink(source, destination) destination.unlink.assert_not_called() destination.symlink_to.assert_not_called() def test_archive_artifact(): target_file = Path("/some/zipfile.zip") destination = "/tmp/null" with patch.object(Path, "unlink") as mock_unlink, patch("docat.utils.ZipFile") as mock_zip: mock_zip_open = MagicMock() mock_zip.return_value.__enter__.return_value.extractall = mock_zip_open extract_archive(target_file, destination) mock_zip.assert_called_once_with(target_file, "r") mock_zip_open.assert_called_once() mock_unlink.assert_called_once() def test_remove_version(temp_project_version): docs = temp_project_version("project", "1.0") remove_docs("project", "1.0", docat.DOCAT_UPLOAD_FOLDER) assert docs.exists() assert not (docs / "project").exists() def test_remove_symlink_version(temp_project_version): project = "project" docs = temp_project_version(project, "1.0") symlink_to_latest = docs / project / "latest" assert symlink_to_latest.is_symlink() remove_docs(project, "latest", docat.DOCAT_UPLOAD_FOLDER) assert not symlink_to_latest.exists() def test_broken_symlinks_in_projects(temp_project_version): project = "project" docs = temp_project_version(project, "1.0") create_symlink(docs / project / "broken", docs / project / "latest") get_dir_size(docs / project) ================================================ FILE: web/.gitignore ================================================ # See https://help.github.com/articles/ignoring-files/ for more about ignoring files. # dependencies /node_modules /.pnp .pnp.js # testing /coverage # production /build /dist # misc .prettierrc .DS_Store .env.local .env.development.local .env.test.local .env.production.local npm-debug.log* yarn-debug.log* yarn-error.log* # local env files .env .env.local .env.*.local ================================================ FILE: web/.prettierignore ================================================ node_modules # Ignore artifacts: build coverage ================================================ FILE: web/.prettierrc.json ================================================ { "trailingComma": "none", "tabWidth": 2, "semi": false, "singleQuote": true } ================================================ FILE: web/README.md ================================================ # docat web ## Project setup ```sh yarn install [--pure-lockfile] ``` ### Compiles and hot-reloads for development The script for `yarn start` automatically sets `VITE_DOCAT_VERSION` to display the current version in the footer, so you can just run: ```sh yarn start ``` ### Compiles and minifies for production To display the current version of docat in the footer, use the following script to set `VITE_DOCAT_VERSION`. This one liner uses the latest tag, if there is one on the current commit, and the current commit if not. ```sh VITE_DOCAT_VERSION=$(git describe --tags --always) yarn build ``` Otherwise you can just use the following and the footer will show `unknown`. ```sh yarn build ``` ### Lints and fixes files ```sh yarn lint ``` ### Tests ```sh yarn test ``` ### Basic Header Theming Not happy with the default Docat logo and header? Just add your custom html header to the `/var/www/html/config.json` file. ```json { "headerHTML": "MyCompany
", "footerHTML": "Contact Maintainers" } ``` ## Development ```sh sudo docker run \ --detach \ --volume /path/to/doc:/var/docat/doc/ \ --publish 8000:80 \ docat ``` ## Errors If you get a 403 response when trying to read a version, try changing the permissions of your docs folder on your host. ```sh sudo chmod 777 /path/to/doc -r ``` ================================================ FILE: web/eslint.config.js ================================================ import eslintReact from "@eslint-react/eslint-plugin"; import eslintJs from "@eslint/js"; import { defineConfig } from "eslint/config"; import tseslint from "typescript-eslint"; import eslintConfigPrettier from "eslint-config-prettier"; import globals from 'globals' export default defineConfig( { files: ["**/*.ts", "**/*.tsx"], ignores: ['dist/**', 'vite-env.d.ts', 'vite.config.ts'], // Extend recommended rule sets from: // 1. ESLint JS's recommended rules // 2. TypeScript ESLint recommended rules // 3. ESLint React's recommended-typescript rules // 4. Prettier (Must be last to disable conflicting rules) extends: [ eslintJs.configs.recommended, tseslint.configs.recommended, eslintReact.configs["recommended-typescript"], eslintConfigPrettier, ], // Configure language/parsing options languageOptions: { ecmaVersion: 'latest', // Allow modern JS syntax globals: { ...globals.browser, // Allow browser globals like `window` }, parser: tseslint.parser, // Your existing parser parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname, }, }, // TODO: See if some of these could be fixed rules: { "@eslint-react/dom-no-dangerously-set-innerhtml": "off", "@eslint-react/exhaustive-deps": "off", "@eslint-react/set-state-in-effect": "off", }, }, ); ================================================ FILE: web/index.html ================================================ ================================================ FILE: web/package.json ================================================ { "name": "docat-web", "version": "0.1.0", "private": true, "type": "module", "dependencies": { "@emotion/react": "^11.14.0", "@emotion/styled": "^11.14.1", "@mui/icons-material": "^9.0.0", "@mui/material": "^9.0.0", "fuse.js": "^7.3.0", "react": "^19.2.5", "react-dom": "^19.2.5", "react-markdown": "^10.1.0", "react-router": "^7.14.0", "react-router-dom": "^7.14.0", "semver": "^7.7.4", "typescript": "^6.0.2", "vite": "^8.0.8" }, "scripts": { "start": "VITE_DOCAT_VERSION=$(git describe --tags --always) vite", "build": "tsc && vite build", "preview": "vite preview", "test": "vitest --watch=false", "lint": "eslint ." }, "browserslist": { "production": [ ">0.2%", "not dead", "not op_mini all" ], "development": [ "last 1 chrome version", "last 1 firefox version", "last 1 safari version" ] }, "devDependencies": { "@vitejs/plugin-react": "^6.0.1", "@eslint/js": "^10.0.1", "@types/semver": "^7.7.1", "@types/node": "^25.6.0", "@types/react": "^19.2.14", "@types/react-dom": "^19.2.3", "jsdom": "^29.0.2", "eslint": "^10.2.0", "eslint-config-prettier": "^10.1.8", "@eslint-react/eslint-plugin": "^4.2.3", "globals": "^17.4.0", "prettier": "^3.8.2", "typescript-eslint": "^8.58.1", "vitest": "^4.1.4" } } ================================================ FILE: web/src/App.tsx ================================================ import React from 'react'; import { createBrowserRouter, RouterProvider } from 'react-router-dom' import { ConfigDataProvider } from './data-providers/ConfigDataProvider' import { MessageBannerProvider } from './data-providers/MessageBannerProvider' import { ProjectDataProvider } from './data-providers/ProjectDataProvider' import { SearchProvider } from './data-providers/SearchProvider' import { StatsDataProvider } from './data-providers/StatsDataProvider' import Claim from './pages/Claim' import Delete from './pages/Delete' import Docs from './pages/Docs' import Help from './pages/Help' import Home from './pages/Home' import NotFound from './pages/NotFound' import Upload from './pages/Upload' function App(): React.JSX.Element { const router = createBrowserRouter([ { path: '/', errorElement:{props.getShareUrl({ useLatest: shareModalUseLatest, hideUi: shareModalHideUi })}
{canCopy && (
{!dragActive && (
{props.label}
)}
)
}
================================================
FILE: web/src/components/Footer.tsx
================================================
import { Box } from '@mui/material'
import { useState, JSX } from 'react'
import { Link } from 'react-router-dom'
import { useConfig } from '../data-providers/ConfigDataProvider'
import styles from './../style/components/Footer.module.css'
export default function Footer(): JSX.Element {
const defaultFooter = (
<>
)
const [footer, setFooter] = useState
{fileName !== '' && (
<>
{fileName}
-
)}Drag zip file here or
{dragActive && ( )}
HELP
{footer}
)
}
================================================
FILE: web/src/components/Header.tsx
================================================
import { useState, JSX } from 'react'
import { Link } from 'react-router-dom'
import { useConfig } from '../data-providers/ConfigDataProvider'
import docatLogo from '../assets/logo.png'
import styles from './../style/components/Header.module.css'
export default function Header(): JSX.Element {
const defaultHeader = (
<>
VERSION{' '}
{import.meta.env.VITE_DOCAT_VERSION ?? 'unknown'}
DOCAT
) const [header, setHeader] = useState
{header}
)
}
================================================
FILE: web/src/components/IFrame.tsx
================================================
import React, { useRef } from 'react'
import { generateKey } from '../data-providers/RandomId'
import styles from '../style/components/IFrame.module.css'
interface Props {
src: string
onPageChanged: (page: string, hash: string, title?: string) => void
onHashChanged: (hash: string) => void
onTitleChanged: (title: string) => void
onNotFound: () => void
onFaviconChanged?: (faviconUrl: string | null) => void
}
export default function IFrame(props: Props): React.JSX.Element {
const iFrameRef = useRef{props.title}
{props.description}
{props.project.logo ?
<>
})
: <>
}
{timeSince(new Date(latestVersion.timestamp))} ago
)
}
================================================
FILE: web/src/components/ProjectList.tsx
================================================
import React from 'react';
import Project from './Project'
import { type Project as ProjectType } from '../models/ProjectsResponse'
import styles from './../style/components/ProjectList.module.css'
interface Props {
projects: ProjectType[]
onFavoriteChanged: () => void
}
export default function ProjectList(props: Props): React.JSX.Element {
if (props.projects.length === 0) {
return <>
}
return (
{props.project.name}{' '}
{latestVersion.name}
{props.project.versions.length === 1
? `${props.project.versions.length} version`
: `${props.project.versions.length} versions`}
{props.project.storage}
{props.projects.map((project) => (
{
props.onFavoriteChanged()
}}
/>
))}
)
}
================================================
FILE: web/src/components/SearchBar.tsx
================================================
import SearchIcon from '@mui/icons-material/Search';
import StarIcon from '@mui/icons-material/Star';
import StarBorderIcon from '@mui/icons-material/StarBorder';
import { Divider, IconButton, InputBase, Paper, Tooltip } from '@mui/material';
import React, { useEffect, useState } from 'react';
import { useSearchParams } from 'react-router-dom';
import { useSearch } from '../data-providers/SearchProvider';
interface Props {
showFavourites: boolean
onShowFavourites: (all: boolean) => void
}
export default function SearchBar(props: Props): React.JSX.Element {
const [showFavourites, setShowFavourites] = useState(true);
const [searchParams, setSearchParams] = useSearchParams();
const { query, setQuery } = useSearch()
const [searchQuery, setSearchQuery] = useState{props.children}
}
================================================
FILE: web/src/data-providers/ConfigDataProvider.tsx
================================================
/* eslint-disable @typescript-eslint/no-explicit-any */
/*
We need any, because we don't know the type of the children
*/
import { createContext, use, useEffect, useState, JSX } from 'react'
export interface Config {
headerHTML?: string
footerHTML?: string
}
const Context = createContextFailed to load projects
404 - Not Found
Sorry, the page you were looking for was not found.
Home
If you want to automate the upload of your documentation consider using{' '}
curl to post it to the server. There are some examples in the{' '}
docat repository
.
{validation.fileMsg}