From 5cb720f4bbef669345ab802199f78627e8de7501 Mon Sep 17 00:00:00 2001 From: ChrisItisdud Date: Fri, 22 Sep 2023 22:41:36 +0200 Subject: [PATCH 1/2] make backend docs work with vitepress --- CONTRIBUTING.md | 25 ++++++++++++++----------- docs/generate_docs.py | 43 +++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 55 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b095d7a..e2e66b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -40,6 +40,7 @@ NOTE: Part of this will only take effect once this repository becomes public. Pl 2. Assign the issue to yourself, or ask to have it assigned to you. 3. Fork [this repository](https://github.com/4lex0017/AudioStreamSplitting) to your own account. 4. Implement your contribution and commit it to your forked repository. Be sure to follow the requirements outlined in [Requirements](#requirements). Test your implementation and ensure the program builds on your system. + - If something about the user workflow, the code structure, available commands or other usage details documented in this document and the [README.md](./README.MD) file is changed, also update the corresponding document(s) accordingly. 5. Create a pull request on this repository. 6. The pull request must be approved by at least two of the main maintainers of AudioStreamSplitting (as of current, that's @chubetho, @ChrisItisdud, @4lex0017 and @JosuaE-FHWS). Reviewers must also attempt to build and run the project locally to verify everything works fine. 7. After two approvals, the pull request gets merged. @@ -108,9 +109,9 @@ Tests are situated in ``backend/tests``. Each module that has unit tests has its - **stores**: All pinia stores, responsible for managing application state, are located in the "stores" directory, facilitating structured state management. - #### Frontend Workflow -1. `main.ts` serves as the entry point for the frontend. It initializes all modules located in the `modules` folder. Eventually, it mounts the `App.vue` component into the DOM. For more details, refer to the [Vue.js documentation](https://vuejs.org/). + +1. `main.ts` serves as the entry point for the frontend. It initializes all modules located in the `modules` folder. Eventually, it mounts the `App.vue` component into the DOM. For more details, refer to the [Vue.js documentation](https://vuejs.org/). 2. `App.vue` acts as the wrapper component for the entire application. It defines the layout, including the sidebar, and the content for each page. @@ -123,7 +124,7 @@ Tests are situated in ``backend/tests``. Each module that has unit tests has its ### Generating documentation -To generate documentation, run ``npm run docs:generate``. You will then find HTML docs for the back-end in docs/_build/html. Also showing the documentation as Github pages is planned for the future, but cannot be done before this repository goes public. +To generate and show documentation, run ``npm run docs``. This will generate back-end and front-end documentation and show it on a local server easily accessible on your browser (usually [localhost:5173](http://localhost:5173/)). Alternatively, you can find HTML docs for the back-end in docs/_build/html. Also showing the documentation as Github pages is planned for the future, but cannot be done before this repository goes public. ## Developing Environment @@ -184,14 +185,16 @@ npm run dev:be #### Available commands -| Command | Description | -| ------------------------ | -------------------------------- | -| npm run `dev:fe` | Run frontend server | -| npm run `dev:be` | Run backend server | -| npm run `view:app` | Run desktop app | -| npm run `build:fe` | Build frontend (html, js, css) | -| npm run `build:app` | Build desktop app | -| npm run `docs:generate` | Generate backend documentation | +| Command | Description | +| ------------------------ | --------------------------------- | +| npm run `dev:fe` | Run frontend server | +| npm run `dev:be` | Run backend server | +| npm run `view:app` | Run desktop app | +| npm run `build:fe` | Build frontend (html, js, css) | +| npm run `build:app` | Build desktop app | +| npm run `docs:gen:be` | Generate backend documentation | +| npm run `docs:gen:fe` | Generate backend documentation | +| npm run `docs` | Generate and show documentation | ## Contributors diff --git a/docs/generate_docs.py b/docs/generate_docs.py index 7567343..c56dcc1 100644 --- a/docs/generate_docs.py +++ b/docs/generate_docs.py @@ -1,6 +1,19 @@ -import platform -import pathlib import os +import pathlib +import platform +import re + + +def replace_dot_with_underscore(matchobj: re.Match): + result = ( + "(" + + matchobj.group(1).replace(".", "_") + + ".md" + + (matchobj.group(2) if matchobj.group(2) is not None else "") + + ")" + ) + return result + file = pathlib.Path(__file__) @@ -20,3 +33,29 @@ os.system(f"{make} clean") os.system(f"{make} html") os.system(f"{make} markdown") + +print( + "Finished generating documentation, renaming and editing files so they work with vitepress..." +) + +folder = file.parent.joinpath("backend", "_build", "markdown") +files = [f for f in os.listdir(folder) if f.endswith(".md")] + +for file_name in files: + file_path = os.path.join(str(folder), file_name) + file_content = "" + with open(file_path, mode="r", encoding="utf8") as file: + file_content = file.read() + os.remove(file_path) + + result_file_name = file_name.replace(".", "_").replace("_md", ".md") + result_file_path = os.path.join(str(folder), result_file_name) + + content_pattern = re.compile(r"\(([A-Za-z\._]+)\.md(#[A-Za-z\.\-_]+)?\)") + result_content = content_pattern.sub(replace_dot_with_underscore, file_content) + + with open(result_file_path, mode="w", encoding="utf8") as result_file: + result_file.seek(0) + result_file.write(result_content) + +print("Finished renaming files!") From 3a87c8564cebfc34bdb0e8b72fe88e9936606df5 Mon Sep 17 00:00:00 2001 From: ChrisItisdud Date: Fri, 22 Sep 2023 23:17:49 +0200 Subject: [PATCH 2/2] add regex comments --- docs/generate_docs.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/generate_docs.py b/docs/generate_docs.py index c56dcc1..996af91 100644 --- a/docs/generate_docs.py +++ b/docs/generate_docs.py @@ -48,9 +48,17 @@ def replace_dot_with_underscore(matchobj: re.Match): file_content = file.read() os.remove(file_path) + # no need for a regex here, we can just replace all "." and then fix the file ending result_file_name = file_name.replace(".", "_").replace("_md", ".md") result_file_path = os.path.join(str(folder), result_file_name) + """ + match all module links. links in markdown files are formatted as + [Display Text](module.submodule.file_name.md#section.to.access) - This will match the + section in normal brackets, and the sub() call will replace all ``.`` in the file + names with ``_``. The section after the # is not affected. + The output for the above example would be ``(module_submodule_file_name.md#section.to.access)``. + """ content_pattern = re.compile(r"\(([A-Za-z\._]+)\.md(#[A-Za-z\.\-_]+)?\)") result_content = content_pattern.sub(replace_dot_with_underscore, file_content)