Merge pull request #26 from this-is-tobi/develop

refactor: remove dead code

.github/workflows/tests-cli.yml

@@ -73,4 +73,4 @@ jobs:
       run: pnpm install --frozen-lockfile
 
     - name: Run cli tests
-      run: ./ci/scripts/run-tests.sh -c
+      run: ./ci/scripts/run-tests.sh -c 'npm,pnpm,bun'

ci/scripts/run-tests.sh

@@ -22,14 +22,15 @@ RUN_LINT="false"
 RUN_UNIT_TESTS="false"
 RUN_CLI_TESTS="false"
 RUN_DOCKER_TESTS="false"
+PACKAGE_MANAGER="npm"
 
 # Declare script helper
 TEXT_HELPER="\nThis script aims to run application tests.
 Following flags are available:
 
-  -c    Run cli tests.
+  -c    Run cli tests (optionally, specify the package manager to be tested as a comma-separated list. Available options are 'npm', 'pnpm' and 'bun', default is '${PACKAGE_MANAGER}')
 
-  -d    Run docker tests (optionally pass the docker image to test as argument).
+  -d    Run docker tests (optionally, specify the docker image to test as argument).
 
   -l    Run lint.
 
@@ -42,11 +43,12 @@ print_help() {
 }
 
 # Parse options
-while getopts hcd:lu flag
+while getopts hc:d:lu flag
 do
   case "${flag}" in
     c)
-      RUN_CLI_TESTS=true;;
+      RUN_CLI_TESTS=true
+      PACKAGE_MANAGER=${OPTARG};;
     d)
       RUN_DOCKER_TESTS=true
       DOCKER_IMAGE=${OPTARG};;
@@ -111,7 +113,7 @@ printf "\nScript settings:
   -> docker buildx version: ${DOCKER_BUILDX_VERSION}
   -> run lint: ${RUN_LINT}
   -> run unit tests: ${RUN_UNIT_TESTS}
-  -> run cli tests: ${RUN_CLI_TESTS}
+  -> run cli tests: ${RUN_CLI_TESTS} (${PACKAGE_MANAGER})
   -> run docker tests: ${RUN_DOCKER_TESTS}\n"
 
 
@@ -144,29 +146,33 @@ if [ "$RUN_CLI_TESTS" == "true" ]; then
     && pnpm pack \
     && TGZ_PKG_NAME=$(ls -d $PWD/* | grep '.tgz')
 
-  mkdir -p /tmp/docpress/cli/pnpm \
-    && cd /tmp/docpress/cli/pnpm \
-    && [ -f "./package.json" ] || pnpm init \
-    && pnpm add $TGZ_PKG_NAME \
-    && pnpm exec docpress -u this-is-tobi -r homelab \
-    && cd - > /dev/null
-  checkDocsResult /tmp/docpress/cli/pnpm/docpress
-
-  mkdir -p /tmp/docpress/cli/npm \
-    && cd /tmp/docpress/cli/npm \
-    && [ -f "./package.json" ] || npm init -y \
-    && npm install $TGZ_PKG_NAME \
-    && npm exec docpress -- -u this-is-tobi -r homelab \
-    && cd - > /dev/null
-  checkDocsResult /tmp/docpress/cli/npm/docpress
-
-  mkdir -p /tmp/docpress/cli/bun \
-    && cd /tmp/docpress/cli/bun \
-    && [ -f "./package.json" ] || bun init \
-    && bun add $TGZ_PKG_NAME \
-    && bunx docpress -u this-is-tobi -r homelab \
-    && cd - > /dev/null
-  checkDocsResult /tmp/docpress/cli/bun/docpress
+  if [[ ",${PACKAGE_MANAGER}," == *",npm,"* ]]; then
+    mkdir -p /tmp/docpress/cli/npm \
+      && cd /tmp/docpress/cli/npm \
+      && [ -f "./package.json" ] || npm init -y \
+      && npm install $TGZ_PKG_NAME \
+      && npm exec docpress -- -U this-is-tobi -r homelab \
+      && cd - > /dev/null
+    checkDocsResult /tmp/docpress/cli/npm/docpress
+  fi
+  if [[ ",${PACKAGE_MANAGER}," == *",pnpm,"* ]]; then
+    mkdir -p /tmp/docpress/cli/pnpm \
+      && cd /tmp/docpress/cli/pnpm \
+      && [ -f "./package.json" ] || pnpm init \
+      && pnpm add $TGZ_PKG_NAME \
+      && pnpm exec docpress -U this-is-tobi -r homelab \
+      && cd - > /dev/null
+    checkDocsResult /tmp/docpress/cli/pnpm/docpress
+  fi
+  if [[ ",${PACKAGE_MANAGER}," == *",bun,"* ]]; then
+    mkdir -p /tmp/docpress/cli/bun \
+      && cd /tmp/docpress/cli/bun \
+      && [ -f "./package.json" ] || bun init -y \
+      && bun add $TGZ_PKG_NAME \
+      && bunx docpress -U this-is-tobi -r homelab \
+      && cd - > /dev/null
+    checkDocsResult /tmp/docpress/cli/bun/docpress
+  fi
 fi
 
 
@@ -179,9 +185,9 @@ if [ "$RUN_DOCKER_TESTS" == "true" ]; then
 
   if [ -n "$DOCKER_IMAGE" ]; then
     mkdir -p /tmp/docpress/docker/docpress \
-      && docker run --name docpress --rm -v /tmp/docpress/docker/docpress:/app/docpress:rw --user root $DOCKER_IMAGE  -u this-is-tobi -r homelab
+      && docker run --name docpress --rm -v /tmp/docpress/docker/docpress:/app/docpress:rw --user root $DOCKER_IMAGE  -U this-is-tobi -r homelab
   else
-    pnpm run build:docker && pnpm run start:docker -u this-is-tobi -r homelab
+    pnpm run build:docker && pnpm run start:docker -U this-is-tobi -r homelab
   fi
 
   checkDocsResult /tmp/docpress/docker/docpress

docs/01-readme.md

@@ -0,0 +1,97 @@
+# Docpress :zap:
+
+This project aims to automate the construction of documentation website based on a Github username and optionally a list of repositories.
+
+## Explanation
+
+Docpress automates the process of downloading documentation files from specified GitHub repositories. Here's how it works:
+
+1. __Repository Documentation Retrieval__:
+    - The program checks if a `docs/` folder is present at the root level of each specified repository.
+    - If the `docs/` folder exists, the entire folder will be downloaded, including all its contents.
+    - If the `docs/` folder is not found, only the `README.md` file will be downloaded.
+
+2. __Static Website Generation__:
+    - After retrieving the documentation files, Docpress generates a static website using [VitePress](https://vitepress.dev/). This framework allows for the creation of fast and customizable documentation sites.
+
+For optimal use of Docpress, please check the [rules section](#rules) to understand the conventions and guidelines that will ensure that everything works correctly. By following these rules, you can maximize the effectiveness of the documentation process.
+
+## Quickstart
+
+1. Generate website using the Docpress docker image.
+    ```sh
+    docker run --name docpress --rm -v $(pwd)/docpress:/app/docpress:rw \
+      ghcr.io/this-is-tobi/docpress -U <github_username>
+    ```
+    > The dist folder is available at `./docpress/.vitepress/dist`, ready to be served by a web server like Nginx, Apache, etc...
+
+2. Start an Nginx docker image using the generated static folder.
+    ```sh
+    docker run --name my-docs --rm -v ./docpress/.vitepress/dist:/usr/share/nginx/html:ro -p 8080:80 \
+      docker.io/nginx
+    ```
+
+3. Access the website at the following address : <http://localhost:8080>.
+
+## Options
+
+CLI description :
+
+```txt
+Usage: docpress [options] [command]
+
+Build your doc website faster than light ⚡️⚡️⚡️
+
+Options:
+  -b, --branch <string>                Branch used to collect Git provider data. (default: "main")
+  -c, --extra-public-content <string>  List of comma separated additional files or directories to process Vitepress public folder.
+  -C, --config <string>                Path to the docpress configuration file.
+  -f, --forks                          Whether or not to create the dedicated fork page that aggregate external contributions.
+  -g, --git-provider <string>          Git provider used to retrieve data. Values should be "github". (default: "github")
+  -h, --help                           display help for command
+  -p, --extra-header-pages <string>    List of comma separated additional files or directories to process Vitepress header pages.
+  -r, --repos-filter <string>          List of comma separated repositories to retrieve from Git provider. Default to all user's public repositories.
+  -t, --extra-theme <string>           List of comma separated additional files or directories to use as Vitepress theme.
+  -T, --token <string>                 Git provider token used to collect data.
+  -U, --username <string>              Git provider username used to collect data.
+  -v, --vitepress-config <string>      Path to the vitepress configuration file.
+  -V, --version                        output the version number
+
+Commands:
+  build [options]                      Build vitepress website.
+  fetch [options]                      Fetch docs with the given username and git provider.
+  prepare [options]                    Transform doc to the target vitepress format.
+```
+
+## Usage methods
+
+Docpress is available through both [npm](https://www.npmjs.com/package/@tobi-or-not/docpress) and [Docker](https://github.com/this-is-tobi/docpress/pkgs/container/docpress), so you can choose the installation method that best suits your environment.
+
+### Using npm (or other package managers)
+
+If you prefer Node.js package managers like npm, pnpm, or bun, you can easily install and run Docpress without additional setup.
+
+To run Docpress using npm:
+```sh
+npx @tobi-or-not/docpress -U <github_username>
+```
+
+> [!TIP]
+> If you’re using a package manager like pnpm or bun, simply replace npx with the corresponding command (pnpx or bunx) to execute Docpress.
+
+### Using Docker
+
+Docpress also provides a Docker image, which is especially useful if you want to avoid installing dependencies directly on your system or if you’re working in a containerized environment. Using Docker ensures a consistent runtime environment.
+
+To run Docpress with Docker:
+```sh
+docker run --rm -v $(pwd)/docpress:/app/docpress:rw ghcr.io/this-is-tobi/docpress -U <github_username>
+```
+
+In this command:
+- `--rm` removes the container after it stops, keeping your environment clean.
+- `-v $(pwd)/docpress:/app/docpress:rw` mounts the `docpress` directory in your current path to the container’s `/app/docpress` folder, allowing Docpress to store generated files locally.
+
+> Ensure Docker is installed and running on your system before using this method.
+
+Both methods provide the same functionality, so you can choose the one that fits your setup or use case.

docs/02-rules.md

@@ -0,0 +1,22 @@
+# Rules
+
+To ensure that the program functions correctly, please follow these conventions:
+
+1. __Documentation folder structure__:
+    - The script will only parse the `docs/` folder located at the root level of the repository. This folder is used to import advanced documentation features, such as multi-page documentation, embedded images, and files.
+
+2. __File naming and sorting__:
+    - If a `docs/` folder is present, all files within it will be sorted and renamed by removing any prefix numbers. This ensures that files appear cleanly in the generated website. For example, `docs/01-get-started.md` will be renamed to `get-started.md`.
+
+3. __Handling the root readme file__:
+    - The `README.md` file located at the root of the repository will only be imported if there is no `./docs/01-readme.md` file present. This allows you to differentiate between the general README and the advanced documentation introduction page.
+    - For instance, you might use the README file for a table of contents that is not relevant in the context of the documentation website.
+
+4. __Link management__:
+    - Any inline link in the `./README.md` file that does not point to `./docs/**` will be replaced with the corresponding GitHub link.
+    - Similarly, any inline link in the `./docs/*.md` files that does not reference `./docs/**` will also be replaced with the appropriate GitHub link.
+
+5. __Project descriptions__:
+    - The project description displayed on the home page of the generated website is extracted from the GitHub repository's description.
+
+By adhering to these rules, you can ensure that your documentation is processed correctly and that it aligns with the intended structure and functionality of the generated site.