Merge pull request #168 from pkalita-lbl/versioned-docs

Use versioned documentation deployment

Author: pkalita-lbl

.github/workflows/build-publish-documentation.yaml

@@ -5,24 +5,25 @@ on:
   push:
     branches:
       - main
-    paths:
-      - "mkdocs.yml"
-      - "linkml_model/model/schema/*.yaml"
-      - "linkml_model/model/docs/*"
 
 jobs:
   github-pages:
     runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
 
     steps:
       #----------------------------------------------
       #       check-out repo and set-up python
       #----------------------------------------------
       - name: Check out repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # fetch all commits/branches so that mike works
 
       - name: Setup Python 3.9
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: 3.9
 
@@ -40,7 +41,7 @@ jobs:
       #----------------------------------------------
       - name: Load cached venv
         id: cached-poetry-dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: .venv
           key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
@@ -50,15 +51,31 @@ jobs:
       #----------------------------------------------
       - name: Install dependencies
         if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
-        run: poetry install --no-interaction --no-root     
-        
+        run: poetry install --no-interaction --no-root
+
+      - name: Configure git user
+        run: |
+          git config user.name "${GITHUB_ACTOR}"
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+          
       #----------------------------------------------
       #           generate markdown files
       #----------------------------------------------
-      - run: make gendoc
+      - name: Generate markdown docs from schema
+        run: make gen-doc
 
       #----------------------------------------------
       #           deploy documentation
       #----------------------------------------------
-      - run: make deploy
-      
+      - name: Deploy generated docs
+        run: |
+          # generate HTML from markdown and put into dev version
+          poetry run mike deploy dev
+          
+          # switch to gh-pages branch, copy over the latest 404.html from main
+          git checkout --force gh-pages
+          git checkout --force main -- 404.html
+          git commit -m "Add 404.html to root" || echo "No changes to 404.html to commit"
+          
+          # push changes to gh-page branch
+          git push origin gh-pages

.github/workflows/codespell.yml

@@ -17,5 +17,6 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
+
       - name: Codespell
         uses: codespell-project/actions-codespell@v2

.github/workflows/main.yaml

@@ -23,10 +23,10 @@ jobs:
       #       check-out repo and set-up python
       #----------------------------------------------
       - name: Check out repository
-        uses: actions/checkout@v2
+        uses: actions/checkout@v3
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -44,7 +44,7 @@ jobs:
       #----------------------------------------------
       - name: Load cached venv
         id: cached-poetry-dependencies
-        uses: actions/cache@v2
+        uses: actions/cache@v3
         with:
           path: .venv
           key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}

.github/workflows/pypi-publish.yaml

@@ -0,0 +1,77 @@
+name: Publish Docs & PyPI Package
+
+on:
+  release:
+    types: [ created ]
+
+jobs:
+  release:
+    name: Create release artifacts
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # fetch all commits/branches so that mike works
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.9
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1.3
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+
+      - name: Install dependencies
+        run: poetry install --no-interaction
+
+      - name: Build source and wheel archives
+        run: |
+          poetry version $(git describe --tags --abbrev=0)
+          poetry build
+
+      - name: Publish distribution to PyPI
+        if: github.repository == 'linkml/linkml'
+        uses: pypa/gh-action-pypi-publish@v1.2.2
+        with:
+          user: __token__
+          password: ${{ secrets.pypi_password }}
+
+      - name: Parse version from tag
+        id: version
+        uses: release-kit/semver@v2
+
+      - name: Configure git user
+        run: |
+          git config user.name "${GITHUB_ACTOR}"
+          git config user.email "${GITHUB_ACTOR}@users.noreply.github.com"
+
+      - name: Generate markdown docs from schema
+        run: make gen-doc
+
+      - name: Deploy docs
+        if: github.event.release.prerelease == false
+        run: |
+          # generate HTML from markdown and put into MAJOR.MINOR version, update "latest" alias
+          poetry run mike deploy --update-aliases ${{ steps.version.outputs.major }}.${{ steps.version.outputs.minor }}.x latest
+          
+          # copy the latest linkml_model files up to the root
+          git checkout --force gh-pages
+          rm -rf linkml_model
+          cp -r latest/linkml_model .
+          git add -A linkml_model
+          git commit -m "Copy latest linkml_model to root level" || echo "No changes to linkml_model to commit"
+          
+          # copy over the latest 404.html from the tag
+          git checkout --force ${{github.event.release.tag_name}} -- 404.html
+          git commit -m "Add 404.html to root" || echo "No changes to 404.html to commit"
+          
+          # push changes to gh-page branch
+          git push origin gh-pages

.github/workflows/release.yaml

@@ -10,6 +10,8 @@ jobs:
   validate-yaml:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
+      - name: Check out repository
+        uses: actions/checkout@v3
+
       - name: Validate YAML file
         run: yamllint -c .yamllint-config linkml_model/model/schema/*.yaml

.github/workflows/validate-yaml-syntax.yaml

@@ -1,6 +1,8 @@
 # Elements that are built using Make
 .venv/
 target/
+staging/
+/docs/
 /make-venv/
 
 # Ignore all of linkml_model except the model directory

.gitignore

@@ -0,0 +1,23 @@
+<!--This file is copied into the root of the documentation branch (gh-pages) after the mkdocs-generated-->
+<!--docs are in place. This file helps redirect paths like:-->
+<!--  * / => /latest-->
+<!--  * /docs/pattern => /latest/docs/pattern-->
+<!--  * /does-not-exist => /latest/404-->
+<!--  * /1.5.x/does-not-exist => /1.5.x/404-->
+
+<script>
+    // Check if the current path is versioned, if not, redirect to the default versioned path
+    const defaultVersion = "latest"
+    const basePath = "/linkml-model"
+    const targetRedirectPath = "404" // path to redirect to, relative to basePath
+
+    const match = window.location.pathname.match(`^${basePath}/(v[0-9.]+|dev|latest)/`)
+    if (match) {
+        // if path starts with version, redirect to versioned 404
+        const versionedPath = `${basePath}/${match[1]}`;
+        window.location.href = `${versionedPath}/${targetRedirectPath}`
+    } else {
+      // if path doesn't start with any version, redirect to defaultVersion
+      window.location.href = window.location.href.replace(basePath, `${basePath}/${defaultVersion}`)
+    }
+</script>

404.html

@@ -23,7 +23,7 @@ The [docs](docs) folder houses the built schema index.
 To build the docs:
 
 ```
-make gendoc
+make gen-doc
 ```
 
 This stages the documentation in target/docs

CONTRIBUTING.md

@@ -11,9 +11,15 @@ RUN = poetry run
 SCHEMA_NAME = linkml_model
 SOURCE_SCHEMA_PATH = $(shell sh ./utils/get-value.sh source_schema_path)
 SRC = .
-DEST = target
-PYMODEL = linkml_model/
-DOCDIR = $(DEST)/docs
+DEST = staging
+PYMODEL = linkml_model
+DOCDIR = docs/source
+
+$(PYMODEL):
+	mkdir -p $@
+
+$(DEST):
+	mkdir -p $@
 
 # basename of a YAML file in model/
 .PHONY: all clean
@@ -34,22 +40,39 @@ status: check-config
 	@echo "Project: $(SCHEMA_NAME)"
 	@echo "Source: $(SOURCE_SCHEMA_PATH)"
 
-setup: install gen-project gendoc git-init-add
+setup: install gen-project gen-doc git-init-add
 
 install:
 	poetry install
 .PHONY: install
 
-all: gen-project gendoc
+all: gen-project gen-doc
 %.yaml: gen-project
-deploy: gendoc mkd-gh-deploy
+deploy: gen-doc mkd-gh-deploy
 
 # generates all project files
 # and updates the artifacts in linkml-model
-gen-project: $(PYMODEL)
-	$(RUN) gen-project -d $(DEST) --config-file gen_project_config.yaml $(SOURCE_SCHEMA_PATH) && mv $(DEST)/*.py $(PYMODEL)
+gen-project: $(PYMODEL) gen-py
+	$(RUN) gen-project -d $(DEST) --config-file gen_project_config.yaml $(SOURCE_SCHEMA_PATH)
 	cp -r $(DEST)/* $(PYMODEL)
-	rm -r $(PYMODEL)/docs
+
+gen-py: $(DEST)
+	# for all the files in the schema folder, run the gen-python command and output the result to the top
+	# level of the project.  In other repos, we'd include mergeimports=True, but we don't do that with
+	# linkml-model.
+	@for file in $(wildcard $(PYMODEL)/model/schema/*.yaml); do \
+		base=$$(basename $$file); \
+		filename_without_suffix=$${base%.*}; \
+		$(RUN) gen-python --genmeta $$file > $(DEST)/$$filename_without_suffix.py; \
+	done
+	cp $(DEST)/*.py $(PYMODEL)
+
+gen-doc:
+	$(RUN) gen-doc --genmeta --sort-by rank -d $(DOCDIR)/docs $(SOURCE_SCHEMA_PATH)
+	cp -r linkml_model/model/docs/* $(DOCDIR)/docs
+	cp -r $(PYMODEL) $(DOCDIR)/$(PYMODEL)
+	rm -rf $(DOCDIR)/$(PYMODEL)/model/docs
+	cp README.md $(DOCDIR)
 
 test: test-schema test-python test-validate-schema
 test-schema:
@@ -85,19 +108,7 @@ upgrade:
 # Test documentation locally
 serve: mkd-serve
 
-# Python datamodel
-$(PYMODEL):
-	mkdir -p $@
-
-
-$(DOCDIR):
-	mkdir -p $@
-
-gendoc: $(DOCDIR)
-	cp -pr linkml_model/model/docs/ $(DOCDIR) ; \
-	$(RUN) gen-doc --genmeta --sort-by rank -d $(DOCDIR) $(SOURCE_SCHEMA_PATH)
-
-testdoc: gendoc serve
+testdoc: gen-doc serve
 
 builddoc:
 	$(RUN) mkdocs build
@@ -120,18 +131,9 @@ git-status:
 
 clean:
 	rm -rf $(DEST)
+	rm -rf docs
 	rm -rf tmp
 
-generate_python_models:
-	# for all the files in the schema folder, run the gen-python command and output the result to the top
-	# level of the project.  In other repos, we'd include mergeimports=True, but we don't do that with
-	# linkml-model.
-	@for file in $(wildcard $(PYMODEL)/model/schema/*.yaml); do \
-		base=$$(basename $$file); \
-		filename_without_suffix=$${base%.*}; \
-		poetry run gen-python --genmeta $$file > $(PYMODEL)/$$filename_without_suffix.py; \
-	done
-
 spell:
 	poetry run codespell