diff --git a/Makefile b/Makefile index f7b9efd3..4edbce07 100644 --- a/Makefile +++ b/Makefile @@ -15,8 +15,9 @@ help: .PHONY: help Makefile -# dry-run build command to double check output build dirs +all: linux windows macos container kubernetes +# dry-run build command to double check output build dirs dryrun: @echo "$(SPHINXBUILD) -M $@ '$(SOURCEDIR)' '$(BUILDDIR)/$(GITDIR)' $(SPHINXOPTS) $(O)" diff --git a/README.md b/README.md index 3c3ec2dd..910bbc6c 100644 --- a/README.md +++ b/README.md @@ -1,124 +1,51 @@ -# MinIO Docs +# MinIO Documentation -# Build Instructions +## Build Instructions -MinIO uses [Sphinx](https://www.sphinx-doc.org/en/master/index.html) to generate -static HTML pages using ReSTructured Text (rST). +MinIO uses [Sphinx](https://www.sphinx-doc.org/en/master/index.html) to generate static HTML pages using ReSTructured Text (rST). -## Prerequisites - -- Python 3.10.X and pip - -- Sphinx 4.3.2 - -- NodeJS 14.5.0 or later and npm - -- gulp.js +### Prerequisites +- Any GNU/Linux Operating System. +- python 3.10.x and python-pip +- sphinx 4.3.2 +- nodejs 14.5.0 or later - `git` or a git-compatible client -- Access to https://github.com/minio/docs +### Build -## Build Process +> NOTE: following instructions do work on macOS for testing purposes, however for production builds GNU/Linux is recommended. -### Linux +1. Clone docs repository locally. -1. Run `git clone https://github.com/minio/docs` and `cd docs` to move into - the working directory. +``` +git clone https://github.com/minio/docs && cd docs/ +``` -2. Create a new virtual environment `python3 -m venv venv`. Activate it using - `source venv/bin/activate`. +2. Create a new Python virtual environment. -3. Run `pip install -r requirements.txt` to setup the Python environment. +``` +python3 -m venv venv && source venv/bin/activate +``` -4. Run `make` to see the available build targets: - - - `make linux` - - `make macos` - - `make windows` - - `make k8s` +3. Install all the python and nodejs dependencies -5. Use `python -m http.server --directory build/GIT_BRANCH//html` - - Open your browser to http://localhost:8000 to view the staged output. +``` +pip install -r requirements.txt && npm install && npm run build +``` -### MacOS +4. Build all targets at once: -1. Run `git clone https://github.com/minio/docs` and `cd docs` to move into - the working directory. +``` +make all +``` -2. Create a new virtual environment `python3 -m venv venv`. Activate it using - `source venv/bin/activate`. +5. View the generated documentation visit http://localhost:8000: -3. Run `pip install -r requirements.txt` to setup the Python environment. +``` +python -m http.server --directory build/YOUR_BRANCH//html +``` -4. Run `npm install` +# License -5. Run `npm run build` - -6. Run `make` to see the available build targets: - - - `make linux` - - `make macos` - - `make windows` - - `make k8s` - -7. Use `python -m http.server --directory build/GIT_BRANCH//html` - - Open your browser to http://localhost:8000 to view the staged output. - -### Windows - -Note: The MinIO Docs builder is designed around the Makefile. -Windows users may have issues in build output. -Consider running Sphinx in a virtual machine or Windows Subsystem for Linux. - -Prereq: - -- Checkout the MinIO docs repository using your preferred `git` method - - `git clone https://github.com/minio/docs` - -All instructions use PowerShell running as an administrator. - -1. Set policies - - `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` -2. Navigate to the folder with the cloned docs -3. Start virtual environment - - `python -m venv venv` -4. Activate virtual environment - - `.\venv\Scripts\Activate.ps1` -5. Install docs requirements - - `pip install -r requirements.txt` -6. (optional) Delete the Build directory - - `Remove-Item build\` -7. Generate CSS from SCSS files - - `npm run build` -8. Build the docs - - `sphinx-build -M html source\ build\GITBRANCH\TAG\ -n -t TAG` - - Replace `TAG` with one of the following supported values: - - - `k8s` - - `linux` - - `macos` - - `windows` - -9. Start the http server - - `python -m http.server --directory build\GITBRANCH\TAG\html` -10. View the staged output in a browser by going to `localhost:8000` - -License -------- - -This project is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/legalcode). - -See [CONTRIBUTIONS](https://github.com/minio/docs/tree/master/CONTRIBUTING.md) for more information on contributing content to the MinIO Documentation project. +This project is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/legalcode). See [CONTRIBUTING.md](https://github.com/minio/docs/tree/master/CONTRIBUTING.md) guide for more information on contributing to the MinIO Documentation project. diff --git a/build-docs.sh b/build-docs.sh index eeee8f2f..920efc34 100755 --- a/build-docs.sh +++ b/build-docs.sh @@ -1,13 +1,14 @@ #!/bin/bash branch=$(git branch --show-current) +export NVM_DIR="/home/minio/.nvm" +[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" # This loads nvm +nvm use stable + +export PATH=${PATH}:${HOME}/.local/bin make clean-all -make k8s -make linux -make container -make windows -make macos +make all sudo mkdir -p /var/www/docs/minio/windows sudo mkdir -p /var/www/docs/minio/macos