diff --git a/bootstrap.sh b/bootstrap.sh new file mode 100755 index 00000000..0cf038c5 --- /dev/null +++ b/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!" diff --git a/readme.rst b/readme.rst index 53a017a4..ff59ef40 100644 --- a/readme.rst +++ b/readme.rst @@ -3,63 +3,40 @@ 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. -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: