83 setup script

bootstrap.sh

@@ -0,0 +1,37 @@
+#!/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 to a temporary directory
+echo "Cloning the starter pack repository..."
+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
+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:\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"
+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
+
+# Clean up
+echo "Cleaning up..."
+rm -rf temp-starter-pack
+
+echo "Setup completed!"

readme.rst

@@ -3,63 +3,40 @@ Documentation starter pack
 
 See the `Sphinx and Read the Docs <https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/>`_ 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.
 
-Set up your documentation repository
-------------------------------------
+Prerequisites
+-------------
 
-You can either create a standalone documentation project based on this repository or include the files from this repository in a dedicated documentation folder in an existing code repository.
+Before you begin, ensure you have the following:
 
-**Note:** We're planning to provide the contents of this repository as an installable package in the future, but currently, you need to copy and update the required files manually.
+ * 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.
 
-Standalone documentation repository
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Bootstrap your documentation repository
+---------------------------------------
 
-To create a standalone documentation repository, clone this starter pack
-repository, `update the configuration <#configure-the-documentation>`_, and
-then commit all files to the documentation repository.
+Bootstrap your repository by following these steps:
 
-You don't need to move any files, and you don't need to do any special
-configuration on Read the Docs.
+ * Copy [bootstrap.sh](bootstrap.sh) to your repository's root directory.
+ * 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".
 
-Here is one way to do this for newly-created fictional docs repository
-``canonical/alpha-docs``:
+This Bash script does the following:
 
-.. code-block:: none
+ * Clones the starter pack GitHub repository
+ * Creates the specified installation directory if necessary
+ * 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
 
-   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 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
-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
----------------
+Build and view the docs
+-----------------------
 
 There are make targets defined in the ``Makefile`` that do various things. To
 get started, we will: