update setup to remove need to build theme, clean up readme, bump pyyaml dep (#555)

README.md

@@ -17,80 +17,101 @@ Sphinx also has directives and extensions to add additional options for formatti
 
 ### Scylla Sphinx Theme
 
-A customized version of the [theme](https://github.com/scylladb/sphinx-scylladb-theme) used by Scylla documentation projects. It also adds a set of custom functionalities and styles.
+A [forked](https://github.com/Start9Labs/sphinx-scylladb-theme/tree/master) version of the [theme](https://github.com/scylladb/sphinx-scylladb-theme) used by Scylla documentation projects. It also adds a set of custom functionalities and styles.
 
 ### Multiversion extension
 
 The [extension](https://github.com/Holzhaus/sphinx-multiversion) used to build docs for different versions.
 
+### Typesense
+
+The open source, integrated [search engine](https://typesense.org/) tool.
+
 ## Dependencies
 
 Install [python3](https://www.python.org/downloads/)
 Install [poetry](https://python-poetry.org/docs/)
-Install [pyenv](https://github.com/pyenv/pyenv)
 
 For installations with macOS:
 
-```
-brew install python3
-brew install poetry
-```
+  ```
+  brew install python3
+  brew install poetry
+  ```
 
 ## Project Setup
 
 1. Clone this repository and enter the project folder:
 
-```
-git clone https://github.com/Start9Labs/documentation.git && cd documentation
-```
+    ```
+    git clone https://github.com/Start9Labs/documentation.git && cd documentation
+    ```
 
 1. Install theme submodule:
 
-```
-git submodule update --init
-```
-
-1. Prep NVM:
-
-```
-nvm use v16.11 || nvm install v16.11 && nvm use v16.11
-```
+    ```
+    git submodule update --init
+    ```
 
 1. Ensure poetry is updated
 
-```
-poetry update
-```
-
-1. Run setup script to install project dependencies:
-
-```
-chmod a+x site/_utils/setup.sh
-./site/_utils/setup.sh
-```
-
-1. Make sure sphinx packages in the package.lock file are preset, for consistency:
-
-```
-cd sphinx-scylladb-theme
-npm ci
-cd ..
-```
+    ```
+    poetry install --no-root
+    ```
 
 1. Navigate to the `site` folder and start the project:
 
-```
-cd site
-make clean && make preview
-```
+    ```
+    cd site
+    make preview
+    ```
 
 ## Development
 
-When editing these files, begin a livereload environment by running `make preview` while in the `./site/` directory.
+The editable files live under `./site/source`. Changes to these files will be picked up by the livereload environment.
 
-When editing any css or table of contents organization changes, the livereload environment must be ended and `make clean` run before starting `make preview` again.
+When table of contents organization changes, the livereload environment needs to be restarted with the following commands:
 
-If you edit something inside `sphinx-scylladb-theme`, you will need to `cd` into that directory and run `npm run build`.
+```
+make clean
+make preview
+```
+
+### Theme development
+
+If you need to make layout or style changes to the theme, you will need to follow a different workflow.
+
+1. Navigate to the theme submodule and install dependencies:
+
+    ```
+    cd sphinx-scylladb-theme
+    npm ci
+    ```
+
+1. Make code changes
+
+1. Build the theme:
+
+    ```
+    npm run build
+    ```
+
+1. Test code changes by restarting the project via `make preview` from the `./site` directory.
+
+1. Commit changes to the theme repo. In the `sphinx-scylladb-theme` directory, run:
+    ```
+    git checkout master
+    git add .
+    git commit -m"<COMMIT_MESSAGE>"
+    git push
+    cd ..
+    # commit the new hash for the theme submodule to the main project
+    git add .
+    git commit -m"update theme"
+    git push
+    ```
+
+Please reach out to @elvece with any questions.
 
 ### Versioning