From 5b467b1a9cd4b07c01c23459062f1aa916bafa44 Mon Sep 17 00:00:00 2001 From: sayalaruano Date: Tue, 23 Sep 2025 10:04:28 +0200 Subject: [PATCH 1/2] =?UTF-8?q?=F0=9F=93=9D=20Docs(docs/Makefile):=20autom?= =?UTF-8?q?ate=20docs=20building=20process?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/Makefile | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 docs/Makefile diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..8fc8119 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,17 @@ +# List of directories to remove +CLEAN_BUILD_DIRS = _build jupyter_execute +CLEAN_DIRS = $(CLEAN_BUILD_DIRS) downloaded reference sections_readme + +.PHONY: clean clean_build + +# Removes the specified directories +clean: + rm -rf $(CLEAN_DIRS) + +clean_build: + rm -rf $(CLEAN_BUILD_DIRS) + +build: + sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/vuegen + python split_readme.py + sphinx-build -n -W --keep-going -b html ./ ./_build/ \ No newline at end of file From 4f7e37b3b334e9a129be545fc1f0cf87fdf57f39 Mon Sep 17 00:00:00 2001 From: sayalaruano Date: Tue, 23 Sep 2025 10:08:43 +0200 Subject: [PATCH 2/2] =?UTF-8?q?=F0=9F=93=9D=20Docs(docs/README.md):=20upda?= =?UTF-8?q?te=20with=20instructions=20to=20use=20makefile?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/README.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/docs/README.md b/docs/README.md index 2c090f5..6e05f57 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,23 +18,34 @@ poetry install --with docs ## Build docs using Sphinx command line tools -Command to be run from `path/to/docs`, i.e. from within the `docs` package folder: +We use `sphinx-apidoc` to create the API reference files from the source code and +`sphinx-build` to create the html files. Also, we use a custom script `split_readme.py` to +split the main `README.md` file into smaller sections for inclusion in the docs. -Options: +We provide a [Makefile](https://github.com/Multiomics-Analytics-Group/vuegen/blob/HEAD/docs/Makefile) +to simplify the cleaning and building process, which you can run from the `docs` folder: -- `--separate` to build separate pages for each (sub-)module +```bash +# pwd: docs +make clean +make build +``` + +Alternatevely, you can run these commands manually each at a time, as follows: ```bash # pwd: docs -# apidoc sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/vuegen -# build docs +python split_readme.py sphinx-build -n -W --keep-going -b html ./ ./_build/ ``` ## Include repo README into docs -The README is included in the `Overview` section of the docs. We created a [Python script](https://github.com/Multiomics-Analytics-Group/vuegen/blob/split-readme-docs/docs/split_readme.py) to split the README sections into separate md files, stored in `docs/sections_readme`. The `index.md` file contains the structure of the docs with the generated sections and additional information. +The README is included in the `Overview` section of the docs. We created a +[Python script](https://github.com/Multiomics-Analytics-Group/vuegen/blob/split-readme-docs/docs/split_readme.py) to +split the README sections into separate md files, stored in `docs/sections_readme`. The `index.md` file contains +the structure of the docs with the generated sections and additional information. Relative links are used in the main README, which need to be resolved when building. It's possible to include the a `relative-docs` option if one uses `index.md` ([see docs](https://myst-parser.readthedocs.io/en/latest/faq/index.html#include-a-file-from-outside-the-docs-folder-like-readme-md)). This does not work