From 24368f3c84cb22ed03b4cb1df9d4b706bdb7d347 Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Mon, 28 Aug 2023 11:18:04 +0100 Subject: [PATCH 01/18] Bootstrap file The file takes the working dir as input Then it copies and updates files as necessary --- bootstrap.sh | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100755 bootstrap.sh diff --git a/bootstrap.sh b/bootstrap.sh new file mode 100755 index 00000000..e1e8be06 --- /dev/null +++ b/bootstrap.sh @@ -0,0 +1,39 @@ +#!/bin/bash + +set +x + +# Ask the user for the installation directory +read -p "Enter the installation directory (e.g., '.' or 'docs'): " install_directory + +# Clone the starter pack repository +echo "Cloning the starter pack repository..." +git clone git@github.com:canonical/sphinx-docs-starter-pack temp-starter-pack +rm -rf temp-starter-pack/.git + +# Create the specified installation directory +echo "Creating the installation directory: $install_directory" +mkdir -p "$install_directory" + +# Copy the contents of the starter pack repository to the installation directory +echo "Copying contents to the installation directory..." +cp -R temp-starter-pack/* temp-starter-pack/.??* "$install_directory" + +# Copy workflow files +echo "Copying workflow files..." +mkdir -p .github/workflows +cp -R "$install_directory/.github/workflows"/* .github/workflows + +# Update working-directory field in workflow files +echo "Updating working directory in workflow files..." +sed -i "s|working-directory: .*|working-directory: $install_directory|g" .github/workflows/* + +# Update .readthedocs.yaml configuration +echo "Updating .readthedocs.yaml configuration..." +sed -i "s|configuration: .*|configuration: $install_directory/conf.py|g" "$install_directory/.readthedocs.yaml" +sed -i "s|requirements: .*|requirements: $install_directory/.sphinx/requirements.txt|g" "$install_directory/.readthedocs.yaml" + +# Clean up +echo "Cleaning up..." +rm -rf temp-starter-pack + +echo "Setup completed!" \ No newline at end of file From ff6af1a0c70d05cc1cc50c5ec7d9833be1de2511 Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Mon, 28 Aug 2023 11:44:52 +0100 Subject: [PATCH 02/18] Updated readme --- readme.rst | 59 +++++++++++++----------------------------------------- 1 file changed, 14 insertions(+), 45 deletions(-) diff --git a/readme.rst b/readme.rst index 53a017a4..70cdd9c0 100644 --- a/readme.rst +++ b/readme.rst @@ -5,61 +5,30 @@ See the `Sphinx and Read the Docs `_, and -then commit all files to the documentation repository. - -You don't need to move any files, and you don't need to do any special -configuration on Read the Docs. +Bootstrap your documentation repository +------------------------------------ -Here is one way to do this for newly-created fictional docs repository -``canonical/alpha-docs``: +Bootstrap your repository by following these steps: -.. code-block:: none + * Copy [bootstrap.sh](bootstrap.sh) to your repository's root directory. + * Run the script: ``./boostrap.sh`` + * Enter the installation directory when prompted. For standalone repos, enter ".". For docs alonside code, enter "docs". - git clone git@github.com:canonical/sphinx-docs-starter-pack alpha-docs - cd alpha-docs - rm -rf .git - git init - git branch -m main - UPDATE THE CONFIGURATION AND BUILD THE DOCS - git add -A - git commit -m "Import sphinx-docs-starter-pack" - git remote add upstream git@github.com:canonical/alpha-docs - git push -f upstream main - -Documentation in a code repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To add documentation to an existing code repository: - -#. create a directory called ``docs`` at the root of the code repository -#. populate the above directory with the contents of the starter pack - repository (with the exception of the ``.git`` directory) -#. copy the file(s) located in the ``docs/.github/workflows`` directory into - the code repository's ``.github/workflows`` directory -#. in the above workflow file(s), change the value of the ``working-directory`` field from ``.`` to ``docs`` -#. in file ``docs/.readthedocs.yaml`` set the following: - - * ``configuration: docs/conf.py`` - * ``requirements: docs/.sphinx/requirements.txt`` +When the script completes, your repository will have the starter sphinx docs files added. Commit your changes. **Note:** When configuring RTD itself for your project, the setting **Path for -.readthedocs.yaml** (under **Advanced Settings**) will need to be given the -value of "docs/.readthedocs.yaml". +.readthedocs.yaml** (under **Advanced Settings**) will need to be given the relative path to ``.readthedocs.yaml``, including the installation directory e.g. ``docs/.readthedocs.yaml``. -Getting started ---------------- +Local Development +----------------- There are make targets defined in the ``Makefile`` that do various things. To get started, we will: From f4f8d8ccdddf12cb23baeec9c47addc6fa1257f2 Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Tue, 29 Aug 2023 11:37:15 +0100 Subject: [PATCH 03/18] Fixes --- readme.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.rst b/readme.rst index 70cdd9c0..3151914c 100644 --- a/readme.rst +++ b/readme.rst @@ -10,7 +10,7 @@ Prerequisites Before you begin, ensure you have the following: - * A GitHub repository where you want to host your documentation. The recommended approach is to host the documentation alonside your code in a `docs` folder. But a standalone docs repo is also an option. + * A GitHub repository where you want to host your documentation. The recommended approach is to host the documentation alongside your code in a `docs` folder. But a standalone docs repo is also an option. * Git and Bash installed on your system. Bootstrap your documentation repository @@ -20,7 +20,7 @@ Bootstrap your repository by following these steps: * Copy [bootstrap.sh](bootstrap.sh) to your repository's root directory. * Run the script: ``./boostrap.sh`` - * Enter the installation directory when prompted. For standalone repos, enter ".". For docs alonside code, enter "docs". + * Enter the installation directory when prompted. For standalone repos, enter ".". For docs alongside code, enter the folder where your docs are e.g. "docs". When the script completes, your repository will have the starter sphinx docs files added. Commit your changes. From 8cb82abaa8ab1780556fce66462664488f6b7125 Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Tue, 29 Aug 2023 11:43:18 +0100 Subject: [PATCH 04/18] Stricter sed Only replace configuration ending with conf.py This prevents overwriting other configuraitons --- bootstrap.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bootstrap.sh b/bootstrap.sh index e1e8be06..3752fa58 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -29,7 +29,7 @@ sed -i "s|working-directory: .*|working-directory: $install_directory|g" .github # Update .readthedocs.yaml configuration echo "Updating .readthedocs.yaml configuration..." -sed -i "s|configuration: .*|configuration: $install_directory/conf.py|g" "$install_directory/.readthedocs.yaml" +sed -i "s|configuration: .*conf\.py|configuration: $install_directory/conf.py|g" "$install_directory/.readthedocs.yaml" sed -i "s|requirements: .*|requirements: $install_directory/.sphinx/requirements.txt|g" "$install_directory/.readthedocs.yaml" # Clean up From f396fddfa722a7488da16d936c3074e59585a306 Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Tue, 29 Aug 2023 11:46:18 +0100 Subject: [PATCH 05/18] Heading fixes --- readme.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.rst b/readme.rst index 3151914c..561b15f0 100644 --- a/readme.rst +++ b/readme.rst @@ -6,7 +6,7 @@ See the `Sphinx and Read the Docs Date: Tue, 29 Aug 2023 11:48:12 +0100 Subject: [PATCH 06/18] Sentence case --- readme.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.rst b/readme.rst index 561b15f0..179b56e6 100644 --- a/readme.rst +++ b/readme.rst @@ -27,7 +27,7 @@ When the script completes, your repository will have the starter sphinx docs fil **Note:** When configuring RTD itself for your project, the setting **Path for .readthedocs.yaml** (under **Advanced Settings**) will need to be given the relative path to ``.readthedocs.yaml``, including the installation directory e.g. ``docs/.readthedocs.yaml``. -Local Development +Local development ----------------- There are make targets defined in the ``Makefile`` that do various things. To From ab7dc7bfe755f03c6fa64307282b0a426c4f3e0d Mon Sep 17 00:00:00 2001 From: Colm Bhandal Date: Tue, 29 Aug 2023 11:49:17 +0100 Subject: [PATCH 07/18] Update readme.rst Co-authored-by: Ruth Fuchss --- readme.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.rst b/readme.rst index 179b56e6..13db79d2 100644 --- a/readme.rst +++ b/readme.rst @@ -19,7 +19,7 @@ Bootstrap your documentation repository Bootstrap your repository by following these steps: * Copy [bootstrap.sh](bootstrap.sh) to your repository's root directory. - * Run the script: ``./boostrap.sh`` + * Run the script: ``./bootstrap.sh`` * Enter the installation directory when prompted. For standalone repos, enter ".". For docs alongside code, enter the folder where your docs are e.g. "docs". When the script completes, your repository will have the starter sphinx docs files added. Commit your changes. From 9cc09a3a381a962cd2c82b68f2e572cf2d1d0c65 Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Tue, 29 Aug 2023 11:51:54 +0100 Subject: [PATCH 08/18] abbreviations Docs and repos Replaced with full words --- readme.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/readme.rst b/readme.rst index 13db79d2..c61d65c5 100644 --- a/readme.rst +++ b/readme.rst @@ -3,14 +3,14 @@ Documentation starter pack See the `Sphinx and Read the Docs `_ guide for instructions on how to get started with Sphinx documentation. -Then go through the following sections to use this starter pack to set up your docs repository. +Then go through the following sections to use this starter pack to set up your documentation repository. Prerequisites ------------- Before you begin, ensure you have the following: - * A GitHub repository where you want to host your documentation. The recommended approach is to host the documentation alongside your code in a `docs` folder. But a standalone docs repo is also an option. + * A GitHub repository where you want to host your documentation. The recommended approach is to host the documentation alongside your code in a `docs` folder. But a standalone documentation repo is also an option. * Git and Bash installed on your system. Bootstrap your documentation repository @@ -20,9 +20,9 @@ Bootstrap your repository by following these steps: * Copy [bootstrap.sh](bootstrap.sh) to your repository's root directory. * Run the script: ``./bootstrap.sh`` - * Enter the installation directory when prompted. For standalone repos, enter ".". For docs alongside code, enter the folder where your docs are e.g. "docs". + * Enter the installation directory when prompted. For standalone repositories, enter ".". For documentation alongside code, enter the folder where your documentation are e.g. "docs". -When the script completes, your repository will have the starter sphinx docs files added. Commit your changes. +When the script completes, your repository will have the starter sphinx documentation files added. Commit your changes. **Note:** When configuring RTD itself for your project, the setting **Path for .readthedocs.yaml** (under **Advanced Settings**) will need to be given the relative path to ``.readthedocs.yaml``, including the installation directory e.g. ``docs/.readthedocs.yaml``. From 39f9800d86f20a14ed8f34223c63de8dd3637931 Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Tue, 29 Aug 2023 11:56:22 +0100 Subject: [PATCH 09/18] Script description --- readme.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/readme.rst b/readme.rst index c61d65c5..01d6a5f0 100644 --- a/readme.rst +++ b/readme.rst @@ -22,6 +22,14 @@ Bootstrap your repository by following these steps: * Run the script: ``./bootstrap.sh`` * Enter the installation directory when prompted. For standalone repositories, enter ".". For documentation alongside code, enter the folder where your documentation are e.g. "docs". +This Bash script does the following: + + * Clones the starter pack GitHub repository + * Creates the specified installation directory if necessary + * Copies contents and workflow files from the starter pack to the installation directory + * Udates working directory paths in workflow files, and updates configuration paths in the .readthedocs.yaml file + * Deletes the cloned repository when it's done + When the script completes, your repository will have the starter sphinx documentation files added. Commit your changes. **Note:** When configuring RTD itself for your project, the setting **Path for From c3ce6b7f9b6837c0a6c165e7d9c0632f72ba98c8 Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Tue, 29 Aug 2023 12:00:45 +0100 Subject: [PATCH 10/18] Review instruction --- readme.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.rst b/readme.rst index 01d6a5f0..6ace2c2f 100644 --- a/readme.rst +++ b/readme.rst @@ -30,7 +30,7 @@ This Bash script does the following: * Udates working directory paths in workflow files, and updates configuration paths in the .readthedocs.yaml file * Deletes the cloned repository when it's done -When the script completes, your repository will have the starter sphinx documentation files added. Commit your changes. +When the script completes, your repository will have the files added that are needed to get started with Sphinx documentation. Review all changes before commiting, then commit your changes. **Note:** When configuring RTD itself for your project, the setting **Path for .readthedocs.yaml** (under **Advanced Settings**) will need to be given the relative path to ``.readthedocs.yaml``, including the installation directory e.g. ``docs/.readthedocs.yaml``. From 4d6020c9b12baff01567d24cc8126de6e7d91c5f Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Tue, 29 Aug 2023 17:24:03 +0100 Subject: [PATCH 11/18] Earlier sed Running sed straight after clone This ensures it's only run against starter pack And it doesn't affect their existing repo --- bootstrap.sh | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/bootstrap.sh b/bootstrap.sh index 3752fa58..486e0daa 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -5,11 +5,18 @@ set +x # Ask the user for the installation directory read -p "Enter the installation directory (e.g., '.' or 'docs'): " install_directory -# Clone the starter pack repository +# Clone the starter pack repository to a temporary directory echo "Cloning the starter pack repository..." git clone git@github.com:canonical/sphinx-docs-starter-pack temp-starter-pack rm -rf temp-starter-pack/.git +# Update file contents for install directory +echo "Updating working directory in workflow files..." +sed -i "s|working-directory: .*|working-directory: $install_directory|g" "temp-starter-pack/.github/workflows"/* +echo "Updating .readthedocs.yaml configuration..." +sed -i "s|configuration: .*conf\.py|configuration: $install_directory/conf.py|g" "temp-starter-pack/.readthedocs.yaml" +sed -i "s|requirements: .*|requirements: $install_directory/.sphinx/requirements.txt|g" "temp-starter-pack/.readthedocs.yaml" + # Create the specified installation directory echo "Creating the installation directory: $install_directory" mkdir -p "$install_directory" @@ -23,15 +30,6 @@ echo "Copying workflow files..." mkdir -p .github/workflows cp -R "$install_directory/.github/workflows"/* .github/workflows -# Update working-directory field in workflow files -echo "Updating working directory in workflow files..." -sed -i "s|working-directory: .*|working-directory: $install_directory|g" .github/workflows/* - -# Update .readthedocs.yaml configuration -echo "Updating .readthedocs.yaml configuration..." -sed -i "s|configuration: .*conf\.py|configuration: $install_directory/conf.py|g" "$install_directory/.readthedocs.yaml" -sed -i "s|requirements: .*|requirements: $install_directory/.sphinx/requirements.txt|g" "$install_directory/.readthedocs.yaml" - # Clean up echo "Cleaning up..." rm -rf temp-starter-pack From 44b5329b702ccc3efe8bb18b8ddd707a5eb8bd2c Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Wed, 30 Aug 2023 14:27:13 +0100 Subject: [PATCH 12/18] build and view --- readme.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/readme.rst b/readme.rst index 6ace2c2f..afc34e12 100644 --- a/readme.rst +++ b/readme.rst @@ -35,8 +35,8 @@ When the script completes, your repository will have the files added that are ne **Note:** When configuring RTD itself for your project, the setting **Path for .readthedocs.yaml** (under **Advanced Settings**) will need to be given the relative path to ``.readthedocs.yaml``, including the installation directory e.g. ``docs/.readthedocs.yaml``. -Local development ------------------ +Build and view the docs +----------------------- There are make targets defined in the ``Makefile`` that do various things. To get started, we will: From 30418ed18858293a81c97930c11adc38f8ba6b27 Mon Sep 17 00:00:00 2001 From: Colm Bhandal Date: Wed, 30 Aug 2023 14:28:52 +0100 Subject: [PATCH 13/18] Spelling Co-authored-by: Ruth Fuchss --- readme.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.rst b/readme.rst index afc34e12..7ef5675e 100644 --- a/readme.rst +++ b/readme.rst @@ -10,7 +10,7 @@ Prerequisites Before you begin, ensure you have the following: - * A GitHub repository where you want to host your documentation. The recommended approach is to host the documentation alongside your code in a `docs` folder. But a standalone documentation repo is also an option. + * A GitHub repository where you want to host your documentation. The recommended approach is to host the documentation alongside your code in a `docs` folder. But a standalone documentation repository is also an option. * Git and Bash installed on your system. Bootstrap your documentation repository From d506a976a805ddd5cfa7578f73a5bee8948b8c1a Mon Sep 17 00:00:00 2001 From: Colm Bhandal Date: Wed, 30 Aug 2023 14:29:12 +0100 Subject: [PATCH 14/18] No history Co-authored-by: Ruth Fuchss --- bootstrap.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bootstrap.sh b/bootstrap.sh index 486e0daa..2060aec3 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -7,7 +7,7 @@ read -p "Enter the installation directory (e.g., '.' or 'docs'): " install_direc # Clone the starter pack repository to a temporary directory echo "Cloning the starter pack repository..." -git clone git@github.com:canonical/sphinx-docs-starter-pack temp-starter-pack +git clone --depth 1 git@github.com:canonical/sphinx-docs-starter-pack temp-starter-pack rm -rf temp-starter-pack/.git # Update file contents for install directory From 5fbe69e2722db769ddbc0bff6418f4348a234f5c Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Wed, 30 Aug 2023 14:33:26 +0100 Subject: [PATCH 15/18] Stricter seds --- bootstrap.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/bootstrap.sh b/bootstrap.sh index 2060aec3..e82f929b 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -14,8 +14,8 @@ rm -rf temp-starter-pack/.git echo "Updating working directory in workflow files..." sed -i "s|working-directory: .*|working-directory: $install_directory|g" "temp-starter-pack/.github/workflows"/* echo "Updating .readthedocs.yaml configuration..." -sed -i "s|configuration: .*conf\.py|configuration: $install_directory/conf.py|g" "temp-starter-pack/.readthedocs.yaml" -sed -i "s|requirements: .*|requirements: $install_directory/.sphinx/requirements.txt|g" "temp-starter-pack/.readthedocs.yaml" +sed -i "s|configuration:\s*conf\.py|configuration: $install_directory/conf.py|g" "temp-starter-pack/.readthedocs.yaml" +sed -i "s|requirements:\s*\.sphinx/requirements\.txt|requirements: $install_directory/.sphinx/requirements.txt|g" "temp-starter-pack/.readthedocs.yaml" # Create the specified installation directory echo "Creating the installation directory: $install_directory" From 0ed4b955b0693cbb5a70467c99a18e7cb44bd23c Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Wed, 30 Aug 2023 14:34:25 +0100 Subject: [PATCH 16/18] Line break --- bootstrap.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bootstrap.sh b/bootstrap.sh index e82f929b..99357d00 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -34,4 +34,4 @@ cp -R "$install_directory/.github/workflows"/* .github/workflows echo "Cleaning up..." rm -rf temp-starter-pack -echo "Setup completed!" \ No newline at end of file +echo "Setup completed!" From b14492f0845e0a5b50c572fd9465428c343aeaed Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Wed, 30 Aug 2023 14:35:35 +0100 Subject: [PATCH 17/18] Reorder steps The description steps need to be reordered The order in the script has changed --- readme.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme.rst b/readme.rst index 7ef5675e..ff59ef40 100644 --- a/readme.rst +++ b/readme.rst @@ -26,8 +26,8 @@ This Bash script does the following: * Clones the starter pack GitHub repository * Creates the specified installation directory if necessary - * Copies contents and workflow files from the starter pack to the installation directory * Udates working directory paths in workflow files, and updates configuration paths in the .readthedocs.yaml file + * Copies contents and workflow files from the starter pack to the installation directory * Deletes the cloned repository when it's done When the script completes, your repository will have the files added that are needed to get started with Sphinx documentation. Review all changes before commiting, then commit your changes. From 0a468e4c5f4817988d9280454548b8cb48965bb8 Mon Sep 17 00:00:00 2001 From: ColmBhandal Date: Thu, 31 Aug 2023 09:26:56 +0100 Subject: [PATCH 18/18] https clone SSH will only work for those with it set up --- bootstrap.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bootstrap.sh b/bootstrap.sh index 99357d00..0cf038c5 100755 --- a/bootstrap.sh +++ b/bootstrap.sh @@ -7,7 +7,7 @@ read -p "Enter the installation directory (e.g., '.' or 'docs'): " install_direc # Clone the starter pack repository to a temporary directory echo "Cloning the starter pack repository..." -git clone --depth 1 git@github.com:canonical/sphinx-docs-starter-pack temp-starter-pack +git clone --depth 1 https://github.com/canonical/sphinx-docs-starter-pack temp-starter-pack rm -rf temp-starter-pack/.git # Update file contents for install directory