diff --git a/docs/help/legacy_docs.md b/docs/help/legacy_docs.md new file mode 100644 index 000000000..45cc3e0db --- /dev/null +++ b/docs/help/legacy_docs.md @@ -0,0 +1,71 @@ +# Viewing legacy documentation + +## Prerequisites + +- Git +- `python3` +- pip + +## Automated Script for Legacy Documentation +To build and view the docs for a specific version of Marvin, you can use [this script](/scripts/serve_legacy_docs). + +You can either clone the [Marvin repo](https://github.com/PrefectHQ/marvin.git) and run the script locally, or copy the script and run it directly in your terminal after making it executable: +```bash +# unix +chmod +x scripts/serve_legacy_docs + +# run the script (default version is v1.5.6) +./scripts/serve_legacy_docs + +# optionally, specify a version +./scripts/serve_legacy_docs v1.5.3 +``` + +## Manual Steps + +If you prefer to manually perform the steps or need to tailor them for your specific operating system, follow these instructions: + +1. **Clone the Repository** + Clone the Marvin repository using Git: + ```bash + git clone https://github.com/PrefectHQ/marvin.git + cd marvin + ``` + +2. **Checkout the Specific Tag** + Checkout the tag for the version you are interested in. Replace `v1.5.6` with the desired version tag: + ```bash + git fetch --tags + git checkout tags/v1.5.6 + ``` + +3. **Create a Virtual Environment** + Create and activate a virtual environment to isolate the dependency installation: + ```bash + python3 -m venv venv + source venv/bin/activate # On Windows, use `venv\Scripts\activate` + ``` + +4. **Install Dependencies** + Install the necessary dependencies for the documentation: + ```bash + pip install -e ".[dev,docs]" + ``` + +5. **Serve the Documentation Locally** + Use `mkdocs` to serve the documentation: + ```bash + mkdocs serve + ``` + This will start a local server. View the documentation by navigating to `http://localhost:8000` in your web browser. + +6. **Exit Virtual Environment** + Once finished, you can exit the virtual environment: + ```bash + deactivate + ``` + + Optionally, you can remove the virtual environment folder: + ```bash + rm -rf venv + ``` \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index f9855e5ac..4fc39e4a5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,7 @@ nav: - welcome/what_is_marvin.md - welcome/installation.md - welcome/quickstart.md + - help/legacy_docs.md - Cookbook: - Entity Deduplication: examples/deduplication.md - Deploying an API: diff --git a/scripts/serve_legacy_docs b/scripts/serve_legacy_docs new file mode 100755 index 000000000..e1e544ee5 --- /dev/null +++ b/scripts/serve_legacy_docs @@ -0,0 +1,69 @@ +#!/bin/bash + +# Setup a temporary directory for cloning +temp_dir=$(mktemp -d) +echo "Using temporary directory: $temp_dir" + +cleanup() { + echo "Cleaning up..." + if [[ "$VIRTUAL_ENV" != "" ]]; then + deactivate + fi + rm -rf "$temp_dir" + trap - INT EXIT + exit +} + +trap cleanup INT EXIT + +command_exists() { + type "$1" &> /dev/null ; +} + +# Determine the Python command to use +PYTHON_CMD="" +if command_exists python3; then + PYTHON_CMD="python3" +elif command_exists python && [[ $(python --version 2>&1) == Python\ 3* ]]; then + PYTHON_CMD="python" +fi + +if [[ -z $PYTHON_CMD ]]; then + echo "Python 3 is not installed." + exit 1 +fi + +if command_exists git && command_exists pip; then + echo "All necessary tools are installed." +else + echo "Please ensure Git and pip are installed." + exit 1 +fi + +REPO_URL="https://github.com/PrefectHQ/marvin.git" +TAG="${1:-v1.5.6}" + +if [[ "$OSTYPE" == "darwin"* ]]; then + export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib +fi + +# Clone the repository into the temporary directory +git clone "$REPO_URL" "$temp_dir/marvin" +cd "$temp_dir/marvin" + +# Check if the tag exists +if git rev-parse "tags/$TAG" >/dev/null 2>&1; then + git checkout "tags/$TAG" +else + echo "Error: Tag '$TAG' not found in the repository." + exit 1 +fi + +# Create and activate a temporary virtual environment +$PYTHON_CMD -m venv temp_env +source temp_env/bin/activate + +pip install "mkdocs-material[imaging]" +pip install -e ".[dev,docs]" +open http://localhost:8000 +mkdocs serve -a localhost:8000