40 |
41 | ### Using DOCAT
42 |
43 | > 🛈 Please note that docat does not provide any way to write documentation.
44 | > It's sole responsibility is to host documentation.
45 | >
46 | > There are many awesome tools to write documenation:
47 | > - [mkdocs](https://www.mkdocs.org/)
48 | > - [sphinx](http://www.sphinx-doc.org/en/master/)
49 | > - [mdbook](https://rust-lang.github.io/mdBook/)
50 | > - ...
51 |
52 |
53 | A CLI tool called [docatl](https://github.com/docat-org/docatl) is available
54 | for easy interaction with the docat server.
55 | However, interacting with docat can also be done through [`curl`](doc/getting-started.md).
56 |
57 | To push documentation (and tag as `latest`) in the folder `docs/` simply run:
58 |
59 | ```sh
60 | docatl push --host http://localhost:8000 ./docs PROJECT VERSION --tag latest
61 | ```
62 |
63 | More detailed instructions can be found in the [**getting started guide**](doc/getting-started.md).
64 |
65 | ## Authentication
66 |
67 | By default, anyone can upload new documentation or add a new version to documentation.
68 | A project can be claimed. A claim returns a token that then must be used
69 | to add or delete versions.
70 |
71 | When hosting docat publicly, it is recommended to use
72 | [http basic auth](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/)
73 | for all `POST`/`PUT` and `DELETE` http calls.
74 |
75 | Hello World
"), "plain/text")} 86 | ) 87 | assert create_response.status_code == 201 88 | 89 | # check detected before hiding 90 | details = get_project_details(docat.DOCAT_UPLOAD_FOLDER, "some-project", include_hidden=True) 91 | assert details == ProjectDetail( 92 | name="some-project", 93 | storage="20 bytes", 94 | versions=[ProjectVersion(name="1.0.0", timestamp=datetime(2000, 1, 1, 1, 1, 0), tags=[], hidden=False)], 95 | ) 96 | 97 | # hide the version 98 | hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) 99 | assert hide_response.status_code == 200 100 | assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} 101 | 102 | # check hidden 103 | details = get_project_details(docat.DOCAT_UPLOAD_FOLDER, "some-project", include_hidden=True) 104 | assert details == ProjectDetail( 105 | name="some-project", 106 | storage="20 bytes", 107 | versions=[ProjectVersion(name="1.0.0", timestamp=datetime(2000, 1, 1, 1, 1, 0), tags=[], hidden=True)], 108 | ) 109 | 110 | 111 | @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) 112 | def test_project_details_without_hidden_versions(_, client_with_claimed_project): 113 | """ 114 | Make sure that project_details works when include_hidden is set to False. 115 | """ 116 | # create a version 117 | create_response = client_with_claimed_project.post( 118 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 119 | ) 120 | assert create_response.status_code == 201 121 | 122 | # check detected before hiding 123 | details = get_project_details(docat.DOCAT_UPLOAD_FOLDER, "some-project", include_hidden=False) 124 | assert details == ProjectDetail( 125 | name="some-project", 126 | storage="20 bytes", 127 | versions=[ProjectVersion(name="1.0.0", timestamp=datetime(2000, 1, 1, 1, 1, 0), tags=[], hidden=False)], 128 | ) 129 | 130 | # hide the version 131 | hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) 132 | assert hide_response.status_code == 200 133 | assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} 134 | 135 | # check hidden 136 | details = get_project_details(docat.DOCAT_UPLOAD_FOLDER, "some-project", include_hidden=False) 137 | assert details == ProjectDetail(name="some-project", storage="20 bytes", versions=[]) 138 | 139 | 140 | @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) 141 | def test_include_hidden_parameter_for_get_projects(_, client_with_claimed_project): 142 | """ 143 | Make sure that include_hidden has the desired effect on the /api/projects endpoint. 144 | """ 145 | # create a version 146 | create_response = client_with_claimed_project.post( 147 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 148 | ) 149 | assert create_response.status_code == 201 150 | 151 | # check detected before hiding 152 | get_projects_response = client_with_claimed_project.get("/api/projects") 153 | assert get_projects_response.status_code == 200 154 | assert get_projects_response.json() == { 155 | "projects": [ 156 | { 157 | "name": "some-project", 158 | "logo": False, 159 | "storage": "20 bytes", 160 | "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], 161 | } 162 | ] 163 | } 164 | 165 | # check include_hidden=True 166 | get_projects_response = client_with_claimed_project.get("/api/projects?include_hidden=true") 167 | assert get_projects_response.status_code == 200 168 | assert get_projects_response.json() == { 169 | "projects": [ 170 | { 171 | "name": "some-project", 172 | "logo": False, 173 | "storage": "20 bytes", 174 | "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], 175 | } 176 | ] 177 | } 178 | 179 | # hide the version 180 | hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) 181 | assert hide_response.status_code == 200 182 | assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} 183 | 184 | # check include_hidden=False 185 | get_projects_response = client_with_claimed_project.get("/api/projects?include_hidden=false") 186 | assert get_projects_response.status_code == 200 187 | assert get_projects_response.json() == {"projects": []} 188 | 189 | # check include_hidden=True 190 | get_projects_response = client_with_claimed_project.get("/api/projects?include_hidden=true") 191 | assert get_projects_response.status_code == 200 192 | assert get_projects_response.json() == { 193 | "projects": [ 194 | { 195 | "name": "some-project", 196 | "logo": False, 197 | "storage": "20 bytes", 198 | "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": True}], 199 | } 200 | ] 201 | } 202 | 203 | 204 | @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) 205 | def test_include_hidden_parameter_for_get_project_details(_, client_with_claimed_project): 206 | """ 207 | Make sure that include_hidden has the desired effect on the /api/project/{project} endpoint. 208 | """ 209 | # create a version 210 | create_response = client_with_claimed_project.post( 211 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 212 | ) 213 | assert create_response.status_code == 201 214 | 215 | # check detected before hiding 216 | get_projects_response = client_with_claimed_project.get("/api/projects/some-project") 217 | assert get_projects_response.status_code == 200 218 | assert get_projects_response.json() == { 219 | "name": "some-project", 220 | "storage": "20 bytes", 221 | "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], 222 | } 223 | 224 | # check include_hidden=True 225 | get_projects_response = client_with_claimed_project.get("/api/projects/some-project?include_hidden=true") 226 | assert get_projects_response.status_code == 200 227 | assert get_projects_response.json() == { 228 | "name": "some-project", 229 | "storage": "20 bytes", 230 | "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], 231 | } 232 | 233 | # hide the version 234 | hide_response = client_with_claimed_project.post("/api/some-project/1.0.0/hide", headers={"Docat-Api-Key": "1234"}) 235 | assert hide_response.status_code == 200 236 | assert hide_response.json() == {"message": "Version 1.0.0 is now hidden"} 237 | 238 | # check include_hidden=False 239 | get_projects_response = client_with_claimed_project.get("/api/projects/some-project?include_hidden=false") 240 | assert get_projects_response.status_code == 200 241 | assert get_projects_response.json() == { 242 | "name": "some-project", 243 | "storage": "20 bytes", 244 | "versions": [], 245 | } 246 | 247 | # check include_hidden=True 248 | get_projects_response = client_with_claimed_project.get("/api/projects/some-project?include_hidden=true") 249 | assert get_projects_response.status_code == 200 250 | assert get_projects_response.json() == { 251 | "name": "some-project", 252 | "storage": "20 bytes", 253 | "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": True}], 254 | } 255 | -------------------------------------------------------------------------------- /docat/tests/test_rename.py: -------------------------------------------------------------------------------- 1 | import io 2 | from pathlib import Path 3 | from unittest.mock import call, patch 4 | 5 | from tinydb import Query 6 | 7 | import docat.app as docat 8 | 9 | 10 | def test_rename_fail_project_does_not_exist(client_with_claimed_project): 11 | with patch("os.rename") as rename_mock: 12 | response = client_with_claimed_project.put("/api/does-not-exist/rename/new-project-name") 13 | assert response.status_code == 404 14 | assert response.json() == {"message": "Project does-not-exist not found"} 15 | 16 | assert rename_mock.mock_calls == [] 17 | 18 | 19 | def test_rename_fail_new_project_name_already_used(client_with_claimed_project): 20 | with patch("os.rename") as rename_mock: 21 | create_first_project_response = client_with_claimed_project.post( 22 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 23 | ) 24 | assert create_first_project_response.status_code == 201 25 | 26 | create_second_project_response = client_with_claimed_project.post( 27 | "/api/second-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 28 | ) 29 | assert create_second_project_response.status_code == 201 30 | 31 | rename_response = client_with_claimed_project.put("/api/some-project/rename/second-project") 32 | assert rename_response.status_code == 409 33 | assert rename_response.json() == {"message": "New project name second-project already in use"} 34 | 35 | assert rename_mock.mock_calls == [] 36 | 37 | 38 | def test_rename_not_authenticated(client_with_claimed_project): 39 | with patch("os.rename") as rename_mock: 40 | create_project_response = client_with_claimed_project.post( 41 | "/api/some-project/1.0.0", 42 | files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}, 43 | ) 44 | assert create_project_response.status_code == 201 45 | 46 | rename_response = client_with_claimed_project.put("/api/some-project/rename/new-project-name") 47 | assert rename_response.status_code == 401 48 | assert rename_response.json() == {"message": "Please provide a header with a valid Docat-Api-Key token for some-project"} 49 | 50 | assert rename_mock.mock_calls == [] 51 | 52 | 53 | def test_rename_success(client_with_claimed_project): 54 | with patch("os.rename") as rename_mock: 55 | create_project_response = client_with_claimed_project.post( 56 | "/api/some-project/1.0.0", 57 | files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}, 58 | ) 59 | assert create_project_response.status_code == 201 60 | 61 | rename_response = client_with_claimed_project.put("/api/some-project/rename/new-project-name", headers={"Docat-Api-Key": "1234"}) 62 | assert rename_response.status_code == 200 63 | assert rename_response.json() == {"message": "Successfully renamed project some-project to new-project-name"} 64 | 65 | old_path = docat.DOCAT_UPLOAD_FOLDER / Path("some-project") 66 | new_path = docat.DOCAT_UPLOAD_FOLDER / Path("new-project-name") 67 | assert rename_mock.mock_calls == [call(old_path, new_path)] 68 | 69 | Project = Query() 70 | table = docat.db.table("claims") 71 | claims_with_old_name = table.search(Project.name == "some-project") 72 | assert len(claims_with_old_name) == 0 73 | claims_with_new_name = table.search(Project.name == "new-project-name") 74 | assert len(claims_with_new_name) == 1 75 | 76 | 77 | def test_rename_rejects_forbidden_project_name(client_with_claimed_project): 78 | """ 79 | Names that conflict with pages in docat web are forbidden, 80 | and renaming a project to such a name should fail. 81 | """ 82 | 83 | create_response = client_with_claimed_project.post( 84 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 85 | ) 86 | assert create_response.status_code == 201 87 | 88 | with patch("os.rename") as rename_mock: 89 | for project_name in ["upload", "claim", "Delete ", "help", "Doc", "API"]: 90 | rename_response = client_with_claimed_project.put(f"/api/some-project/rename/{project_name}", headers={"Docat-Api-Key": "1234"}) 91 | assert rename_response.status_code == 400 92 | assert rename_response.json() == { 93 | "message": f'New project name "{project_name}" is forbidden, as it conflicts with pages in docat web.' 94 | } 95 | 96 | assert rename_mock.mock_calls == [] 97 | -------------------------------------------------------------------------------- /docat/tests/test_stats.py: -------------------------------------------------------------------------------- 1 | import io 2 | from datetime import datetime 3 | from unittest.mock import patch 4 | 5 | import pytest 6 | 7 | 8 | @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) 9 | @pytest.mark.parametrize( 10 | ("project_config", "n_projects", "n_versions", "storage"), 11 | [ 12 | ([("some-project", ["1.0.0"])], 1, 1, "20 bytes"), 13 | ([("some-project", ["1.0.0", "2.0.0"])], 1, 2, "40 bytes"), 14 | ([("some-project", ["1.0.0", "2.0.0"])], 1, 2, "40 bytes"), 15 | ([("some-project", ["1.0.0", "2.0.0"]), ("another-project", ["1"])], 2, 3, "60 bytes"), 16 | ], 17 | ) 18 | def test_get_stats(_, project_config, n_projects, n_versions, storage, client_with_claimed_project): 19 | """ 20 | Make sure that get_stats works. 21 | """ 22 | # create a version 23 | for project_name, versions in project_config: 24 | for version in versions: 25 | create_response = client_with_claimed_project.post( 26 | f"/api/{project_name}/{version}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 27 | ) 28 | assert create_response.status_code == 201 29 | 30 | # get system stats 31 | hide_response = client_with_claimed_project.get("/api/stats") 32 | assert hide_response.status_code == 200 33 | assert hide_response.json() == {"n_projects": n_projects, "n_versions": n_versions, "storage": storage} 34 | -------------------------------------------------------------------------------- /docat/tests/test_upload.py: -------------------------------------------------------------------------------- 1 | import io 2 | from pathlib import Path 3 | from unittest.mock import call, patch 4 | 5 | import docat.app as docat 6 | 7 | 8 | def test_successfully_upload(client): 9 | with patch("docat.app.remove_docs"): 10 | response = client.post("/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}) 11 | response_data = response.json() 12 | 13 | assert response.status_code == 201 14 | assert response_data["message"] == "Documentation uploaded successfully" 15 | assert (docat.DOCAT_UPLOAD_FOLDER / "some-project" / "1.0.0" / "index.html").exists() 16 | 17 | 18 | def test_successfully_override(client_with_claimed_project): 19 | with patch("docat.app.remove_docs") as remove_mock: 20 | response = client_with_claimed_project.post( 21 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 22 | ) 23 | assert response.status_code == 201 24 | 25 | response = client_with_claimed_project.post( 26 | "/api/some-project/1.0.0", 27 | files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}, 28 | headers={"Docat-Api-Key": "1234"}, 29 | ) 30 | response_data = response.json() 31 | 32 | assert response.status_code == 201 33 | assert response_data["message"] == "Documentation uploaded successfully" 34 | assert remove_mock.mock_calls == [call("some-project", "1.0.0", docat.DOCAT_UPLOAD_FOLDER)] 35 | 36 | 37 | def test_tags_are_not_overwritten_without_api_key(client_with_claimed_project): 38 | with patch("docat.app.remove_docs") as remove_mock: 39 | response = client_with_claimed_project.post( 40 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 41 | ) 42 | assert response.status_code == 201 43 | 44 | response = client_with_claimed_project.put("/api/some-project/1.0.0/tags/latest") 45 | assert response.status_code == 201 46 | 47 | response = client_with_claimed_project.post( 48 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 49 | ) 50 | response_data = response.json() 51 | 52 | assert response.status_code == 401 53 | assert response_data["message"] == "Please provide a header with a valid Docat-Api-Key token for some-project" 54 | assert remove_mock.mock_calls == [] 55 | 56 | 57 | def test_successful_tag_creation(client_with_claimed_project): 58 | with patch("docat.app.create_symlink") as create_symlink_mock: 59 | create_project_response = client_with_claimed_project.post( 60 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 61 | ) 62 | assert create_project_response.status_code == 201 63 | 64 | create_tag_response = client_with_claimed_project.put("/api/some-project/1.0.0/tags/latest") 65 | 66 | assert create_tag_response.status_code == 201 67 | assert create_tag_response.json() == {"message": "Tag latest -> 1.0.0 successfully created"} 68 | 69 | destination_path = docat.DOCAT_UPLOAD_FOLDER / Path("some-project") / Path("latest") 70 | assert create_symlink_mock.mock_calls == [call("1.0.0", destination_path), call().__bool__()] 71 | 72 | 73 | def test_create_tag_fails_when_version_does_not_exist(client_with_claimed_project): 74 | with patch("docat.app.create_symlink") as create_symlink_mock: 75 | create_project_response = client_with_claimed_project.post( 76 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 77 | ) 78 | 79 | assert create_project_response.status_code == 201 80 | 81 | create_tag_response = client_with_claimed_project.put("/api/some-project/non-existing-version/tags/new-tag") 82 | 83 | assert create_tag_response.status_code == 404 84 | assert create_tag_response.json() == {"message": "Version non-existing-version not found"} 85 | 86 | assert create_symlink_mock.mock_calls == [] 87 | 88 | 89 | def test_create_tag_fails_on_overwrite_of_version(client_with_claimed_project): 90 | """ 91 | Create a tag with the same name as a version. 92 | """ 93 | project_name = "some-project" 94 | version = "1.0.0" 95 | tag = "latest" 96 | 97 | create_first_project_response = client_with_claimed_project.post( 98 | f"/api/{project_name}/{version}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 99 | ) 100 | assert create_first_project_response.status_code == 201 101 | 102 | create_second_project_response = client_with_claimed_project.post( 103 | f"/api/{project_name}/{tag}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 104 | ) 105 | assert create_second_project_response.status_code == 201 106 | 107 | create_tag_response = client_with_claimed_project.put(f"/api/{project_name}/{version}/tags/{tag}") 108 | assert create_tag_response.status_code == 409 109 | assert create_tag_response.json() == {"message": f"Tag {tag} would overwrite an existing version!"} 110 | 111 | 112 | def test_create_fails_on_overwrite_of_tag(client_with_claimed_project): 113 | """ 114 | Create a version with the same name as a tag. 115 | """ 116 | project_name = "some-project" 117 | version = "1.0.0" 118 | tag = "some-tag" 119 | 120 | create_project_response = client_with_claimed_project.post( 121 | f"/api/{project_name}/{version}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 122 | ) 123 | assert create_project_response.status_code == 201 124 | 125 | create_tag_response = client_with_claimed_project.put(f"/api/{project_name}/{version}/tags/{tag}") 126 | assert create_tag_response.status_code == 201 127 | assert create_tag_response.json() == {"message": f"Tag {tag} -> {version} successfully created"} 128 | 129 | create_project_with_name_of_tag_response = client_with_claimed_project.post( 130 | f"/api/{project_name}/{tag}", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 131 | ) 132 | assert create_project_with_name_of_tag_response.status_code == 409 133 | assert create_project_with_name_of_tag_response.json() == {"message": "Cannot overwrite existing tag with new version."} 134 | 135 | 136 | def test_fails_with_invalid_token(client_with_claimed_project): 137 | with patch("docat.app.remove_docs") as remove_mock: 138 | response = client_with_claimed_project.post( 139 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 140 | ) 141 | assert response.status_code == 201 142 | 143 | response = client_with_claimed_project.post( 144 | "/api/some-project/1.0.0", 145 | files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")}, 146 | headers={"Docat-Api-Key": "456"}, 147 | ) 148 | response_data = response.json() 149 | 150 | assert response.status_code == 401 151 | assert response_data["message"] == "Docat-Api-Key token is not valid for some-project" 152 | 153 | assert remove_mock.mock_calls == [] 154 | 155 | 156 | def test_upload_rejects_forbidden_project_name(client_with_claimed_project): 157 | """ 158 | Names that conflict with pages in docat web are forbidden, 159 | and creating a project with such a name should fail. 160 | """ 161 | 162 | with patch("docat.app.remove_docs") as remove_mock: 163 | for project_name in ["upload", "claim", " Delete ", "help", "DOC", "api"]: 164 | response = client_with_claimed_project.post( 165 | f"/api/{project_name}/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 166 | ) 167 | assert response.status_code == 400 168 | assert response.json() == {"message": f'Project name "{project_name}" is forbidden, as it conflicts with pages in docat web.'} 169 | 170 | assert remove_mock.mock_calls == [] 171 | 172 | 173 | def test_upload_issues_warning_missing_index_file(client_with_claimed_project): 174 | """ 175 | When a project is uploaded without an index.html file, 176 | a warning should be issued, but the upload should succeed. 177 | """ 178 | 179 | response = client_with_claimed_project.post( 180 | "/api/some-project/1.0.0", files={"file": ("some-other-file.html", io.BytesIO(b"Hello World
"), "plain/text")} 181 | ) 182 | response_data = response.json() 183 | 184 | assert response.status_code == 201 185 | assert response_data["message"] == "Documentation uploaded successfully, but no index.html found at root of archive." 186 | assert (docat.DOCAT_UPLOAD_FOLDER / "some-project" / "1.0.0" / "some-other-file.html").exists() 187 | assert not (docat.DOCAT_UPLOAD_FOLDER / "some-project" / "1.0.0" / "index.html").exists() 188 | -------------------------------------------------------------------------------- /docat/tests/test_upload_icon.py: -------------------------------------------------------------------------------- 1 | import base64 2 | import io 3 | from datetime import datetime 4 | from unittest.mock import call, patch 5 | 6 | import docat.app as docat 7 | 8 | ONE_PIXEL_PNG = base64.decodebytes( 9 | b"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAAAXNSR0IArs4c6QAAAA1JREFUGFdjYGBg+A8AAQQBAHAgZQsAAAAASUVORK5CYII=" 10 | ) 11 | 12 | 13 | def test_successful_icon_upload(client_with_claimed_project): 14 | upload_folder_response = client_with_claimed_project.post( 15 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 16 | ) 17 | assert upload_folder_response.status_code == 201 18 | 19 | with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: 20 | upload_response = client_with_claimed_project.post( 21 | "/api/some-project/icon", 22 | files={"file": ("icon.jpg", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, 23 | ) 24 | 25 | assert upload_response.status_code == 200 26 | assert upload_response.json() == {"message": "Icon successfully uploaded"} 27 | assert remove_file_mock.mock_calls == [] 28 | assert len(copyfileobj_mock.mock_calls) == 1 29 | 30 | 31 | def test_icon_upload_fails_with_no_project(client_with_claimed_project): 32 | with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: 33 | upload_response = client_with_claimed_project.post( 34 | "/api/non-existing-project/icon", 35 | files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, 36 | ) 37 | 38 | assert upload_response.status_code == 404 39 | assert upload_response.json() == {"message": "Project non-existing-project not found"} 40 | assert remove_file_mock.mock_calls == [] 41 | assert copyfileobj_mock.mock_calls == [] 42 | 43 | 44 | def test_icon_upload_fails_no_token_and_existing_icon(client): 45 | """ 46 | upload twice, first time should be successful (nothing replaced), 47 | second time should fail (would need token to replace) 48 | """ 49 | 50 | upload_folder_response = client.post( 51 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 52 | ) 53 | assert upload_folder_response.status_code == 201 54 | 55 | with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: 56 | upload_response_1 = client.post( 57 | "/api/some-project/icon", 58 | files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, 59 | ) 60 | assert upload_response_1.status_code == 200 61 | assert upload_response_1.json() == {"message": "Icon successfully uploaded"} 62 | assert remove_file_mock.mock_calls == [] 63 | assert len(copyfileobj_mock.mock_calls) == 1 64 | 65 | with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: 66 | upload_response_2 = client.post( 67 | "/api/some-project/icon", 68 | files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, 69 | ) 70 | assert upload_response_2.status_code == 401 71 | assert upload_response_2.json() == {"message": "Please provide a header with a valid Docat-Api-Key token for some-project"} 72 | assert remove_file_mock.mock_calls == [] 73 | assert len(copyfileobj_mock.mock_calls) == 0 74 | 75 | 76 | def test_icon_upload_successful_replacement_with_token(client_with_claimed_project): 77 | """ 78 | upload twice, both times should be successful (token provided) 79 | """ 80 | 81 | icon_path = docat.DOCAT_UPLOAD_FOLDER / "some-project" / "logo" 82 | 83 | upload_folder_response = client_with_claimed_project.post( 84 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 85 | ) 86 | assert upload_folder_response.status_code == 201 87 | 88 | with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: 89 | upload_response_1 = client_with_claimed_project.post( 90 | "/api/some-project/icon", 91 | files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, 92 | headers={"Docat-Api-Key": "1234"}, 93 | ) 94 | assert upload_response_1.status_code == 200 95 | assert upload_response_1.json() == {"message": "Icon successfully uploaded"} 96 | assert remove_file_mock.mock_calls == [] 97 | assert len(copyfileobj_mock.mock_calls) == 1 98 | 99 | with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: 100 | upload_response_1 = client_with_claimed_project.post( 101 | "/api/some-project/icon", 102 | files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, 103 | headers={"Docat-Api-Key": "1234"}, 104 | ) 105 | assert upload_response_1.status_code == 200 106 | assert upload_response_1.json() == {"message": "Icon successfully uploaded"} 107 | assert remove_file_mock.mock_calls == [call(icon_path)] 108 | assert len(copyfileobj_mock.mock_calls) == 1 109 | 110 | 111 | def test_icon_upload_successful_no_token_no_existing_icon(client): 112 | upload_folder_response = client.post( 113 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 114 | ) 115 | assert upload_folder_response.status_code == 201 116 | 117 | with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: 118 | upload_response = client.post( 119 | "/api/some-project/icon", 120 | files={"file": ("icon.png", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, 121 | ) 122 | 123 | assert upload_response.status_code == 200 124 | assert upload_response.json() == {"message": "Icon successfully uploaded"} 125 | assert remove_file_mock.mock_calls == [] 126 | assert len(copyfileobj_mock.mock_calls) == 1 127 | 128 | 129 | def test_icon_upload_fails_no_image(client_with_claimed_project): 130 | upload_folder_response = client_with_claimed_project.post( 131 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 132 | ) 133 | assert upload_folder_response.status_code == 201 134 | 135 | with patch("shutil.copyfileobj") as copyfileobj_mock, patch("os.remove") as remove_file_mock: 136 | upload_response = client_with_claimed_project.post( 137 | "/api/some-project/icon", 138 | files={"file": ("file.zip", io.BytesIO(b"not image data"), "application/zip")}, 139 | ) 140 | 141 | assert upload_response.status_code == 400 142 | assert upload_response.json() == {"message": "Icon must be an image"} 143 | assert remove_file_mock.mock_calls == [] 144 | assert copyfileobj_mock.mock_calls == [] 145 | 146 | 147 | @patch("docat.utils.get_version_timestamp", return_value=datetime(2000, 1, 1, 1, 1, 0)) 148 | def test_get_project_recongizes_icon(_, client_with_claimed_project): 149 | """ 150 | get_projects should return true, if the project has an icon 151 | """ 152 | 153 | upload_folder_response = client_with_claimed_project.post( 154 | "/api/some-project/1.0.0", files={"file": ("index.html", io.BytesIO(b"Hello World
"), "plain/text")} 155 | ) 156 | assert upload_folder_response.status_code == 201 157 | 158 | projects_response = client_with_claimed_project.get("/api/projects") 159 | assert projects_response.status_code == 200 160 | assert projects_response.json() == { 161 | "projects": [ 162 | { 163 | "name": "some-project", 164 | "logo": False, 165 | "storage": "20 bytes", 166 | "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], 167 | } 168 | ] 169 | } 170 | 171 | upload_response = client_with_claimed_project.post( 172 | "/api/some-project/icon", 173 | files={"file": ("icon.jpg", io.BytesIO(ONE_PIXEL_PNG), "image/png")}, 174 | ) 175 | assert upload_response.status_code == 200 176 | 177 | projects_response = client_with_claimed_project.get("/api/projects") 178 | assert projects_response.status_code == 200 179 | assert projects_response.json() == { 180 | "projects": [ 181 | { 182 | "name": "some-project", 183 | "logo": True, 184 | "storage": "103 bytes", 185 | "versions": [{"name": "1.0.0", "timestamp": "2000-01-01T01:01:00", "tags": [], "hidden": False}], 186 | } 187 | ] 188 | } 189 | -------------------------------------------------------------------------------- /docat/tests/test_utils.py: -------------------------------------------------------------------------------- 1 | from pathlib import Path 2 | from unittest.mock import MagicMock, patch 3 | 4 | import docat.app as docat 5 | from docat.utils import create_symlink, extract_archive, remove_docs 6 | 7 | 8 | def test_symlink_creation(): 9 | """ 10 | Tests the creation of a symlink 11 | """ 12 | source = MagicMock() 13 | destination = MagicMock() 14 | destination.exists.return_value = False 15 | destination.symlink_to.return_value = MagicMock() 16 | 17 | assert create_symlink(source, destination) 18 | 19 | destination.symlink_to.assert_called_once_with(source) 20 | 21 | 22 | def test_symlink_creation_overwrite_destination(): 23 | """ 24 | Tests the creation of a symlink and overwriting 25 | of existing symlink 26 | """ 27 | source = MagicMock() 28 | destination = MagicMock() 29 | destination.exists.return_value = True 30 | destination.is_symlink.return_value = True 31 | destination.unlink.return_value = MagicMock() 32 | destination.symlink_to.return_value = MagicMock() 33 | 34 | assert create_symlink(source, destination) 35 | 36 | destination.unlink.assert_called_once() 37 | destination.symlink_to.assert_called_once_with(source) 38 | 39 | 40 | def test_symlink_creation_do_not_overwrite_destination(): 41 | """ 42 | Tests wether a symlinc is not created when it 43 | would overwrite an existing version 44 | """ 45 | source = MagicMock() 46 | destination = MagicMock() 47 | destination.exists.return_value = True 48 | destination.is_symlink.return_value = False 49 | destination.unlink.return_value = MagicMock() 50 | destination.symlink_to.return_value = MagicMock() 51 | 52 | assert not create_symlink(source, destination) 53 | 54 | destination.unlink.assert_not_called() 55 | destination.symlink_to.assert_not_called() 56 | 57 | 58 | def test_archive_artifact(): 59 | target_file = Path("/some/zipfile.zip") 60 | destination = "/tmp/null" 61 | with patch.object(Path, "unlink") as mock_unlink, patch("docat.utils.ZipFile") as mock_zip: 62 | mock_zip_open = MagicMock() 63 | mock_zip.return_value.__enter__.return_value.extractall = mock_zip_open 64 | 65 | extract_archive(target_file, destination) 66 | 67 | mock_zip.assert_called_once_with(target_file, "r") 68 | mock_zip_open.assert_called_once() 69 | mock_unlink.assert_called_once() 70 | 71 | 72 | def test_remove_version(temp_project_version): 73 | docs = temp_project_version("project", "1.0") 74 | remove_docs("project", "1.0", docat.DOCAT_UPLOAD_FOLDER) 75 | 76 | assert docs.exists() 77 | assert not (docs / "project").exists() 78 | 79 | 80 | def test_remove_symlink_version(temp_project_version): 81 | project = "project" 82 | docs = temp_project_version(project, "1.0") 83 | symlink_to_latest = docs / project / "latest" 84 | assert symlink_to_latest.is_symlink() 85 | 86 | remove_docs(project, "latest", docat.DOCAT_UPLOAD_FOLDER) 87 | 88 | assert not symlink_to_latest.exists() 89 | -------------------------------------------------------------------------------- /web/.gitignore: -------------------------------------------------------------------------------- 1 | # See https://help.github.com/articles/ignoring-files/ for more about ignoring files. 2 | 3 | # dependencies 4 | /node_modules 5 | /.pnp 6 | .pnp.js 7 | 8 | # testing 9 | /coverage 10 | 11 | # production 12 | /build 13 | /dist 14 | 15 | # misc 16 | .prettierrc 17 | .DS_Store 18 | .env.local 19 | .env.development.local 20 | .env.test.local 21 | .env.production.local 22 | 23 | npm-debug.log* 24 | yarn-debug.log* 25 | yarn-error.log* 26 | 27 | # local env files 28 | .env 29 | .env.local 30 | .env.*.local 31 | -------------------------------------------------------------------------------- /web/.prettierignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | # Ignore artifacts: 3 | build 4 | coverage 5 | -------------------------------------------------------------------------------- /web/.prettierrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "trailingComma": "none", 3 | "tabWidth": 2, 4 | "semi": false, 5 | "singleQuote": true 6 | } 7 | -------------------------------------------------------------------------------- /web/README.md: -------------------------------------------------------------------------------- 1 | # docat web 2 | 3 | ## Project setup 4 | 5 | ```sh 6 | yarn install [--pure-lockfile] 7 | ``` 8 | 9 | ### Compiles and hot-reloads for development 10 | 11 | The script for `yarn start` automatically sets `VITE_DOCAT_VERSION` to display the current version in the footer, 12 | so you can just run: 13 | 14 | ```sh 15 | yarn start 16 | ``` 17 | 18 | ### Compiles and minifies for production 19 | 20 | To display the current version of docat in the footer, use the following script to set `VITE_DOCAT_VERSION`. 21 | This one liner uses the latest tag, if there is one on the current commit, and the current commit if not. 22 | 23 | ```sh 24 | VITE_DOCAT_VERSION=$(git describe --tags --always) yarn build 25 | ``` 26 | 27 | Otherwise you can just use the following and the footer will show `unknown`. 28 | 29 | ```sh 30 | yarn build 31 | ``` 32 | 33 | ### Lints and fixes files 34 | 35 | ```sh 36 | yarn lint 37 | ``` 38 | 39 | ### Tests 40 | 41 | ```sh 42 | yarn test 43 | ``` 44 | 45 | ### Basic Header Theming 46 | 47 | Not happy with the default Docat logo and header? 48 | Just add your custom html header to the `/var/www/html/config.json` file. 49 | 50 | ```json 51 | { 52 | "headerHTML": "MyCompany
", 53 | "footerHTML": "Contact Maintainers" 54 | } 55 | ``` 56 | 57 | 58 | ## Development 59 | 60 | ```sh 61 | sudo docker run \ 62 | --detach \ 63 | --volume /path/to/doc:/var/docat/doc/ \ 64 | --publish 8000:80 \ 65 | docat 66 | ``` 67 | 68 | ## Errors 69 | 70 | If you get a 403 response when trying to read a version, 71 | try changing the permissions of your docs folder on your host. 72 | 73 | ```sh 74 | sudo chmod 777 /path/to/doc -r 75 | ``` 76 | -------------------------------------------------------------------------------- /web/eslint.config.js: -------------------------------------------------------------------------------- 1 | import js from '@eslint/js' 2 | import pluginReact from 'eslint-plugin-react' 3 | import pluginPrettier from 'eslint-plugin-prettier' 4 | import pluginTypescriptEslint from '@typescript-eslint/eslint-plugin' 5 | import parserTypescriptEslint from '@typescript-eslint/parser' 6 | import { globalIgnores } from 'eslint/config' 7 | 8 | export default [ 9 | globalIgnores(['vite-env.d.ts', 'vite.config.ts', 'dist/**/*']), 10 | js.configs.recommended, 11 | { 12 | files: ['*.ts', '*.tsx'], 13 | languageOptions: { 14 | parser: parserTypescriptEslint, 15 | parserOptions: { 16 | project: './tsconfig.json' 17 | } 18 | }, 19 | plugins: { 20 | '@typescript-eslint': pluginTypescriptEslint 21 | }, 22 | rules: { 23 | ...pluginTypescriptEslint.configs['recommended'].rules, 24 | ...pluginTypescriptEslint.configs['recommended-requiring-type-checking'] 25 | .rules, 26 | '@typescript-eslint/space-before-function-paren': 'off', 27 | '@typescript-eslint/no-extra-semi': 'off' 28 | } 29 | }, 30 | { 31 | files: ['*.js', '*.jsx', '*.ts', '*.tsx'], 32 | plugins: { 33 | react: pluginReact, 34 | prettier: pluginPrettier 35 | }, 36 | languageOptions: { 37 | ecmaVersion: 'latest', 38 | globals: { 39 | window: 'readonly', 40 | document: 'readonly', 41 | navigator: 'readonly' 42 | } 43 | }, 44 | rules: { 45 | ...pluginReact.configs.recommended.rules, 46 | ...pluginPrettier.configs.recommended.rules 47 | }, 48 | settings: { 49 | react: { 50 | version: 'detect' 51 | } 52 | } 53 | } 54 | ] 55 | -------------------------------------------------------------------------------- /web/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 13 | 14 | 15 | 16 | 17 | -------------------------------------------------------------------------------- /web/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "docat-web", 3 | "version": "0.1.0", 4 | "private": true, 5 | "type": "module", 6 | "dependencies": { 7 | "@emotion/react": "^11.11.3", 8 | "@emotion/styled": "^11.10.6", 9 | "@mui/icons-material": "^6.1.3", 10 | "@mui/material": "^6.1.3", 11 | "@types/jest": "^29.5.11", 12 | "@types/lodash": "^4.14.202", 13 | "@types/node": "^22.7.5", 14 | "@types/react": "^18.2.45", 15 | "@types/react-dom": "^18.2.18", 16 | "@typescript-eslint/parser": "^8.8.1", 17 | "@vitejs/plugin-react-swc": "^3.6.0", 18 | "eslint": "^9.12.0", 19 | "eslint-config-react-app": "^7.0.1", 20 | "fuse.js": "^7.0.0", 21 | "jsdom": "^25.0.1", 22 | "lodash": "^4.17.21", 23 | "react": "^18.2.0", 24 | "react-dom": "^18.2.0", 25 | "react-markdown": "^9.0.1", 26 | "react-router": "^6.21.1", 27 | "react-router-dom": "^6.21.1", 28 | "semver": "^7.5.4", 29 | "typescript": "*", 30 | "vite": "^5.4.8", 31 | "vite-plugin-svgr": "^4.2.0", 32 | "vitest": "^2.1.2", 33 | "web-vitals": "^4.2.3" 34 | }, 35 | "scripts": { 36 | "start": "VITE_DOCAT_VERSION=$(git describe --tags --always) vite", 37 | "build": "tsc && vite build", 38 | "preview": "vite preview", 39 | "test": "vitest --watch=false", 40 | "lint": "eslint" 41 | }, 42 | "browserslist": { 43 | "production": [ 44 | ">0.2%", 45 | "not dead", 46 | "not op_mini all" 47 | ], 48 | "development": [ 49 | "last 1 chrome version", 50 | "last 1 firefox version", 51 | "last 1 safari version" 52 | ] 53 | }, 54 | "devDependencies": { 55 | "@typescript-eslint/eslint-plugin": "^8.8.1", 56 | "eslint-config-prettier": "^9.1.0", 57 | "eslint-config-standard-with-typescript": "^43.0.1", 58 | "eslint-plugin-import": "^2.29.1", 59 | "eslint-plugin-n": "^17.11.1", 60 | "eslint-plugin-prettier": "^5.1.3", 61 | "eslint-plugin-promise": "^7.1.0", 62 | "eslint-plugin-react": "^7.32.1", 63 | "prettier": "^3.2.4" 64 | } 65 | } 66 | -------------------------------------------------------------------------------- /web/public/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docat-org/docat/9837dc0d3f0db303a0706dfcc5b2a3533bc45407/web/public/favicon.ico -------------------------------------------------------------------------------- /web/src/App.tsx: -------------------------------------------------------------------------------- 1 | import { createBrowserRouter, RouterProvider } from 'react-router-dom' 2 | import { ConfigDataProvider } from './data-providers/ConfigDataProvider' 3 | import { MessageBannerProvider } from './data-providers/MessageBannerProvider' 4 | import { ProjectDataProvider } from './data-providers/ProjectDataProvider' 5 | import { SearchProvider } from './data-providers/SearchProvider' 6 | import { StatsDataProvider } from './data-providers/StatsDataProvider' 7 | import Claim from './pages/Claim' 8 | import Delete from './pages/Delete' 9 | import Docs from './pages/Docs' 10 | import Help from './pages/Help' 11 | import Home from './pages/Home' 12 | import NotFound from './pages/NotFound' 13 | import Upload from './pages/Upload' 14 | 15 | function App(): JSX.Element { 16 | const router = createBrowserRouter([ 17 | { 18 | path: '/', 19 | errorElement:
69 |
70 |
71 |
72 |
73 |
74 |
76 |
77 |
78 |
79 |
80 |
81 | )
82 | }
83 |
84 | export default App
85 |
--------------------------------------------------------------------------------
/web/src/assets/getting-started.md:
--------------------------------------------------------------------------------
1 | ../../../doc/getting-started.md
--------------------------------------------------------------------------------
/web/src/assets/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/docat-org/docat/9837dc0d3f0db303a0706dfcc5b2a3533bc45407/web/src/assets/logo.png
--------------------------------------------------------------------------------
/web/src/components/DataSelect.tsx:
--------------------------------------------------------------------------------
1 | import { FormGroup, MenuItem, TextField } from '@mui/material'
2 | import React, { useState } from 'react'
3 |
4 | interface Props {
5 | emptyMessage: string
6 | errorMsg?: string
7 | value?: string
8 | label: string
9 | values: string[]
10 | onChange: (value: string) => void
11 | }
12 |
13 | export default function DataSelect(props: Props): JSX.Element {
14 | const [selectedValue, setSelectedValue] = useState
55 |
56 |
57 |
60 |
61 |
62 |
91 |
92 |
93 |
94 |
102 |
103 |
104 | {
107 | setShareModalOpen(false)
108 | }}
109 | aria-labelledby="share-modal-title"
110 | aria-describedby="share-modal-description"
111 | >
112 |
168 |
169 | )
170 | }
171 |
--------------------------------------------------------------------------------
/web/src/components/FavoriteStar.tsx:
--------------------------------------------------------------------------------
1 | import { Star, StarOutline } from '@mui/icons-material'
2 | import { useState } from 'react'
3 | import ProjectRepository from '../repositories/ProjectRepository'
4 |
5 | interface Props {
6 | projectName: string
7 | onFavoriteChanged: () => void
8 | }
9 |
10 | export default function FavoriteStar(props: Props): JSX.Element {
11 | const [isFavorite, setIsFavorite] = useState
113 |
132 | {
137 | setShareModalHideUi(e.target.checked)
138 | }}
139 | />
140 | }
141 | label="Hide Version Selector"
142 | className={styles['share-modal-label']}
143 | />
144 | {
149 | setShareModalUseLatest(e.target.checked)
150 | }}
151 | />
152 | }
153 | label="Always use latest version"
154 | className={styles['share-modal-label']}
155 | />
156 |
157 |
158 |
166 |
167 |
114 |
130 |
131 | {getShareUrl()}
115 | {canCopy && ( 116 |
117 |
127 |
128 | )}
129 |
94 | {!dragActive && (
95 |
96 | {props.label}
97 |
98 | )}
99 |
100 |
142 | )
143 | }
144 |
--------------------------------------------------------------------------------
/web/src/components/Footer.tsx:
--------------------------------------------------------------------------------
1 | import { Box } from '@mui/material'
2 | import { useState } from 'react'
3 | import { Link } from 'react-router-dom'
4 | import { useConfig } from '../data-providers/ConfigDataProvider'
5 | import styles from './../style/components/Footer.module.css'
6 |
7 | export default function Footer(): JSX.Element {
8 |
9 | const defaultFooter = (
10 | <>
11 | )
12 |
13 | const [footer, setFooter] = useState
109 |
117 |
118 | {fileName !== '' && (
119 | <>
120 |
141 | {fileName}
121 |-
122 | 123 | )} 124 | 125 |Drag zip file here or
126 | 127 | 130 | 131 | {dragActive && ( 132 | 139 | )} 140 |
23 |
24 | HELP
25 |
26 |
27 |
28 | {footer}
29 |
30 |
31 |
38 | )
39 | }
40 |
--------------------------------------------------------------------------------
/web/src/components/Header.tsx:
--------------------------------------------------------------------------------
1 | import { useState } from 'react'
2 | import { Link } from 'react-router-dom'
3 |
4 | import { useConfig } from '../data-providers/ConfigDataProvider'
5 |
6 | import docatLogo from '../assets/logo.png'
7 | import styles from './../style/components/Header.module.css'
8 |
9 |
10 | export default function Header(): JSX.Element {
11 | const defaultHeader = (
12 | <>
13 |
32 |
33 | VERSION{' '}
34 | {import.meta.env.VITE_DOCAT_VERSION ?? 'unknown'}
35 |
36 |
37 | DOCAT
15 | 16 | ) 17 | 18 | const [header, setHeader] = useState
28 | {header}
29 |
30 | )
31 | }
32 |
--------------------------------------------------------------------------------
/web/src/components/IFrame.tsx:
--------------------------------------------------------------------------------
1 | import React, { useRef } from 'react'
2 | import { uniqueId } from 'lodash'
3 |
4 | import styles from '../style/components/IFrame.module.css'
5 | interface Props {
6 | src: string
7 | onPageChanged: (page: string, hash: string, title?: string) => void
8 | onHashChanged: (hash: string) => void
9 | onTitleChanged: (title: string) => void
10 | onNotFound: () => void
11 | }
12 |
13 | export default function IFrame(props: Props): JSX.Element {
14 | const iFrameRef = useRef
15 |
27 | )
28 | }
29 |
--------------------------------------------------------------------------------
/web/src/components/PageLayout.tsx:
--------------------------------------------------------------------------------
1 | import styles from './../style/components/PageLayout.module.css'
2 | import Footer from './Footer'
3 | import Header from './Header'
4 | import NavigationTitle from './NavigationTitle'
5 |
6 | interface Props {
7 | title: string
8 | description?: string | JSX.Element
9 | showSearchBar?: boolean
10 | children: JSX.Element | JSX.Element[]
11 | }
12 |
13 | export default function PageLayout(props: Props): JSX.Element {
14 | return (
15 | <>
16 |
16 |
20 |
24 |
25 | {props.title}
23 |{props.description}
26 |
18 |
21 |
22 |
23 | )
24 | }
25 |
--------------------------------------------------------------------------------
/web/src/components/Project.tsx:
--------------------------------------------------------------------------------
1 | import { Link } from 'react-router-dom'
2 | import { type Project as ProjectType } from '../models/ProjectsResponse'
3 | import ProjectRepository from '../repositories/ProjectRepository'
4 | import styles from './../style/components/Project.module.css'
5 |
6 | import { Box, Tooltip, Typography } from '@mui/material'
7 | import FavoriteStar from './FavoriteStar'
8 |
9 | interface Props {
10 | project: ProjectType
11 | onFavoriteChanged: () => void
12 | }
13 |
14 | function timeSince(date: Date) {
15 | const seconds = Math.floor((new Date().getTime() - date.getTime()) / 1000);
16 | let interval = seconds / 31536000;
17 |
18 | if (interval > 1) {
19 | return Math.floor(interval) + " years";
20 | }
21 | interval = seconds / 2592000;
22 | if (interval > 1) {
23 | return Math.floor(interval) + " months";
24 | }
25 | interval = seconds / 86400;
26 | if (interval > 1) {
27 | return Math.floor(interval) + " days";
28 | }
29 | interval = seconds / 3600;
30 | if (interval > 1) {
31 | return Math.floor(interval) + " hours";
32 | }
33 | interval = seconds / 60;
34 | if (interval > 1) {
35 | return Math.floor(interval) + " minutes";
36 | }
37 | return Math.floor(seconds) + " seconds";
38 | }
39 |
40 | export default function Project(props: Props): JSX.Element {
41 | const latestVersion = ProjectRepository.getLatestVersion(props.project.versions)
42 |
43 | return (
44 |
45 |
46 | {props.project.logo ?
47 | <>
48 |
49 | })
54 |
55 | : <>
56 | }
57 |
58 |
93 | )
94 | }
95 |
--------------------------------------------------------------------------------
/web/src/components/ProjectList.tsx:
--------------------------------------------------------------------------------
1 | import Project from './Project'
2 |
3 | import { type Project as ProjectType } from '../models/ProjectsResponse'
4 | import styles from './../style/components/ProjectList.module.css'
5 |
6 | interface Props {
7 | projects: ProjectType[]
8 | onFavoriteChanged: () => void
9 | }
10 |
11 | export default function ProjectList(props: Props): JSX.Element {
12 | if (props.projects.length === 0) {
13 | return <>
14 | }
15 |
16 | return (
17 |
59 |
60 |
69 |
75 | {timeSince(new Date(latestVersion.timestamp))} ago
76 |
77 |
78 |
79 |
61 | {props.project.name}{' '}
62 |
63 | {latestVersion.name}
64 |
65 |
66 |
67 |
68 |
80 |
92 |
81 | {props.project.versions.length === 1
82 | ? `${props.project.versions.length} version`
83 | : `${props.project.versions.length} versions`}
84 | {props.project.storage}
85 |
86 |
87 |
18 | {props.projects.map((project) => (
19 | {
23 | props.onFavoriteChanged()
24 | }}
25 | />
26 | ))}
27 |
28 | )
29 | }
30 |
--------------------------------------------------------------------------------
/web/src/components/SearchBar.tsx:
--------------------------------------------------------------------------------
1 | import SearchIcon from '@mui/icons-material/Search';
2 | import StarIcon from '@mui/icons-material/Star';
3 | import StarBorderIcon from '@mui/icons-material/StarBorder';
4 | import { Divider, IconButton, InputBase, Paper, Tooltip } from '@mui/material';
5 | import React, { useEffect, useState } from 'react';
6 | import { useSearchParams } from 'react-router-dom';
7 | import { useSearch } from '../data-providers/SearchProvider';
8 |
9 |
10 | interface Props {
11 | showFavourites: boolean
12 | onShowFavourites: (all: boolean) => void
13 | }
14 |
15 | export default function SearchBar(props: Props): JSX.Element {
16 | const [showFavourites, setShowFavourites] = useState(true);
17 | const [searchParams, setSearchParams] = useSearchParams();
18 |
19 | const { query, setQuery } = useSearch()
20 | const [searchQuery, setSearchQuery] = React.useState{props.children}
13 | }
14 |
--------------------------------------------------------------------------------
/web/src/data-providers/ConfigDataProvider.tsx:
--------------------------------------------------------------------------------
1 | /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return */
2 | /*
3 | We need any, because we don't know the type of the children,
4 | and we need the return those children again which is an "unsafe return"
5 | */
6 |
7 | import { createContext, useContext, useEffect, useState } from 'react'
8 |
9 | export interface Config {
10 | headerHTML?: string
11 | footerHTML?: string
12 | }
13 |
14 | const Context = createContext
56 |
63 | )
64 | }
65 |
66 | if (projects == null || stats == null) {
67 | return
58 |
61 |
62 | Failed to load projects
60 |
72 |
213 | )
214 | }
215 |
--------------------------------------------------------------------------------
/web/src/pages/IframePageNotFound.tsx:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 | import { Link } from 'react-router-dom'
3 | import Footer from '../components/Footer'
4 | import Header from '../components/Header'
5 | import styles from './../style/pages/IframePageNotFound.module.css'
6 |
7 | interface Props {
8 | project: string
9 | version: string
10 | hideUi: boolean
11 | }
12 |
13 | export default function IframeNotFound(props: Props): JSX.Element {
14 | const link = `/${props.project}/${props.version}${props.hideUi ? '?hide-ui' : ''}`
15 |
16 | return (
17 |
75 |
76 |
77 |
78 |
87 |
88 |
95 |
97 |
98 |
99 |
100 |
104 |
106 |
107 |
108 |
109 |
113 |
115 |
116 |
117 |
118 |
122 |
124 |
125 |
126 |
127 |
128 | { projects.length === 0 ?
129 | <>{ query !== "" ?
130 |
131 | Couldn't find any docs
132 | :
133 |
134 | Looks like you don't have any docs yet.
135 |
138 |
139 | } :
140 | <>
141 | { (query || showAll) ?
142 | {
145 | updateFavorites()
146 | }}
147 | />
148 | :
149 | <>
150 | FAVOURITES
151 | { (favoriteProjects.length === 0) ?
152 |
153 | No docs favourited at the moment, search for docs or
154 |
157 |
158 | :
159 | <>
160 | {
163 | updateFavorites()
164 | }}
165 | />
166 |
167 |
170 | onShowFavourites(true)} >
171 | SHOW ALL DOCS
172 |
175 |
176 | }
177 |
178 | }
179 |
180 | }
181 |
182 |
194 | INSTANCE STATS
195 | #
198 | DOCS
199 | {stats.n_projects}
200 |
201 | #
203 | VERSIONS
204 | {stats.n_versions}
205 |
206 | STORAGE
208 | {stats.storage}
209 |
210 |
211 |
212 |
18 |
32 | )
33 | }
34 |
--------------------------------------------------------------------------------
/web/src/pages/LoadingPage.tsx:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 | import Footer from '../components/Footer'
3 | import Header from '../components/Header'
4 |
5 | export default function LoadingPage(): JSX.Element {
6 | return (
7 | <>
8 |
20 |
30 |
31 | 21 | 404 - Not Found 22 |
23 |24 | Sorry, the page you were looking for was not found in this version. 25 |
26 | 27 | Back to Project Home 28 | 29 |
10 |
22 | )
23 | }
24 |
--------------------------------------------------------------------------------
/web/src/pages/Upload.tsx:
--------------------------------------------------------------------------------
1 | import { TextField } from '@mui/material'
2 | import React, { useState } from 'react'
3 |
4 | import FileInput from '../components/FileInput'
5 | import PageLayout from '../components/PageLayout'
6 | import StyledForm from '../components/StyledForm'
7 | import { useMessageBanner } from '../data-providers/MessageBannerProvider'
8 | import { useProjects } from '../data-providers/ProjectDataProvider'
9 | import ProjectRepository from '../repositories/ProjectRepository'
10 | import LoadingPage from './LoadingPage'
11 |
12 | import styles from '../style/pages/Upload.module.css'
13 |
14 | interface Validation {
15 | projectMsg?: string
16 | versionMsg?: string
17 | fileMsg?: string
18 | }
19 |
20 | const okFileTypes = [
21 | 'application/zip',
22 | 'zip',
23 | 'application/octet-stream',
24 | 'application/x-zip',
25 | 'application/x-zip-compressed'
26 | ]
27 |
28 | export default function Upload(): JSX.Element {
29 | document.title = 'Upload | docat'
30 |
31 | const { reload: reloadProjects } = useProjects()
32 | const { showMessage } = useMessageBanner()
33 |
34 | const [project, setProject] = useState
12 |
20 |
21 | 404 - Not Found
13 |14 | Sorry, the page you were looking for was not found. 15 |
16 | 17 | Home 18 | 19 |
143 | If you want to automate the upload of your documentation consider using{' '}
144 | curl to post it to the server. There are some examples in the{' '}
145 |
150 | docat repository
151 |
152 | .
153 |
201 | {validation.fileMsg} 202 |
203 | 204 | 207 |