initialise github pages for documentation (#38)

Initialise documentation with Github Pages and Sphinx
buildingSMART · Mar 29, 2024 · 6b87c14 · 6b87c14
1 parent cc388a8
commit 6b87c14
Show file tree

Hide file tree

Showing 21 changed files with 1,010 additions and 0 deletions.
diff --git a/.github/workflows/build-and-deploy-docs.yml b/.github/workflows/build-and-deploy-docs.yml
@@ -0,0 +1,31 @@
+name: "Build docs with Sphinx and deploy to Github Pages"
+
+on: 
+  push:
+    branches: gh-pages
+
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+      pages: write
+    env:
+      INPUT_DOCS-FOLDER: docs
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build HTML
+      uses: civilx64/sphinx-action@master
+      with:
+        docs-folder: docs/
+    - name: Setup Pages
+      uses: actions/configure-pages@v4
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        # Upload html docs
+        path: './docs/_build/html'
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4
diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
@@ -0,0 +1,28 @@
+name: "Build docs with Sphinx"
+
+on: 
+  pull_request:
+    branches: gh-pages
+
+jobs:
+  build_and_deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+      pages: write
+    env:
+      INPUT_DOCS-FOLDER: docs
+    steps:
+    - uses: actions/checkout@v4
+    - name: Build HTML
+      uses: civilx64/sphinx-action@master
+      with:
+        docs-folder: docs/
+    - name: Setup Pages
+      uses: actions/configure-pages@v4
+    - name: Upload artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        # Upload html docs
+        path: './docs/_build/html'
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+_build/
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico
diff --git a/docs/_static/user_auth.png b/docs/_static/user_auth.png
diff --git a/docs/_static/user_include_passed_na_etc.png b/docs/_static/user_include_passed_na_etc.png
diff --git a/docs/_static/user_results_icons.png b/docs/_static/user_results_icons.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,31 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'buildingSMART Validation Service'
+copyright = '2024, buildingSMART International'
+author = 'buildingSMART International'
+release = '0.6'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx_rtd_theme',
+    'myst_parser',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+html_favicon = '_static/favicon.ico'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
diff --git a/docs/dev/functional_parts.md b/docs/dev/functional_parts.md
@@ -0,0 +1,35 @@
+# Functional parts
+
+Functional parts refer to logical grouping of rules that involve similar types of validation.
+
+These functional part prefixes are used in the naming of the normative rules
+and are reported in the results listed by the validation service.
+
+## Catalog
+
+| Code | Functional part                  | Gherkin tag | Notes                                            |
+|------|----------------------------------|-------------|--------------------------------------------------|
+| ALA  | Alignment Agreement              | @ALA        |                                                  |
+| ALB  | Alignment (business logic)       | @ALB        |                                                  |
+| ALG  | Alignment (geometry)             | @ALG        |                                                  |
+| ALS  | Alignment (segments)             | @ALS        |                                                  |
+| APA  |                                  | @PSE        |                                                  |
+| ASM  | Assembling                       | @ASM        |                                                  |
+| AXG  | Axis geometry                    | @AXG        |                                                  |
+| CLS  | Classification reference         | @CLS        |                                                  |
+| GEM  | Geometric representation         | @GEM        | Shall be further decomposed                      |
+| GRF  | Georeferencing                   | @GRF        |                                                  |
+| GRP  | Grouping                         | @GRP        |                                                  |
+| IBP  | Industry Best Practice           | @IBP        | Used for @industry-practice tag                  |
+| IFC  | IFC                              | @IFC        | Validating correct IFC Schema                    |
+| LIB  | Library reference                | @LIB        |                                                  |
+| LIP  | Linear placement (non-geometric) | @LIP        |                                                  |
+| MAT  | Materials                        | @MAT        |                                                  |
+| MDS  | Model setup                      | @MDS        |                                                  |
+| OJP  | Object placement                 | @OJP        |                                                  |
+| OJT  | Object typing                    | @OJT        |                                                  |
+| PRP  | Properties                       | @PRP        |                                                  |
+| PSE  | Property Sets                    | @PSE        |                                                  |
+| SPS  | Spatial structure                | @SPS        | Need to split SS aggregation and SS containment? |
+| STN  | Stationing                       | @STN        |                                                  |
+| SYS  |                                  | @SYS        |                                                  |
diff --git a/docs/dev/gherkin_deep_dive.md b/docs/dev/gherkin_deep_dive.md
@@ -0,0 +1,9 @@
+# A deep dive into gherkin rule implementations
+
+TODO: Ghesselink
+
+## Decorator
+
+## Context stacking
+
+## Validaton Outcomes
diff --git a/docs/dev/ifc_gherkin_rules_readme.md b/docs/dev/ifc_gherkin_rules_readme.md
@@ -0,0 +1,61 @@
+# IFC Gherkin rules
+
+## Usage as part of buildingSMART validation service
+
+This repository is one of three submodules in the overall validation service.  See (application_structure) for more information.
+
+## Making changes
+
+The rules developed in this repository follow the general ideas of Gherkin and its python implementation behave.
+
+This means there are human readable definitions of rules and Python implementations.
+
+A third component of this repository are minimal sample files with expected outcomes, which means that extensions and modifications can be suggested with confidence of not breaking existing functionality.
+
+## Command line usage
+
+Informal propositions and implementer agreements written in Gherkin for automatic validation of IFC building models using steps implemented in IfcOpenShell.
+
+```shell
+$ python -m ifc-gherkin-rules ifc-gherkin-rules\test\files\gem001\fail-gem001-cube-advanced-brep.ifc
+Feature: Shell geometry propositions/IfcClosedShell.v1
+    URL: /blob/8dbd61e/features/geometry.shells.feature
+
+   Step: Every oriented edge shall be referenced exactly 1 times by the loops of the face
+
+       * #29=IfcClosedShell((#104,#115,#131,#147,#163,#179))
+         On instance #29=IfcClosedShell((#104,...,#179)) the edge (-0.183012701892219,
+         0.683012701892219, 1.0) -> (-0.683012701892219, -0.183012701892219, 1.0) was
+         referenced 2 times
+
+       * #29=IfcClosedShell((#104,#115,#131,#147,#163,#179))
+         On instance #29=IfcClosedShell((#104,...,#179)) the edge (-0.5, -0.5, 0.0) ->
+         (-0.5, 0.5, 0.0) was referenced 2 times
+
+       * #29=IfcClosedShell((#104,#115,#131,#147,#163,#179))
+         On instance #29=IfcClosedShell((#104,...,#179)) the edge (-0.5, 0.5, 0.0) ->
+         (0.5, 0.5, 0.0) was referenced 2 times
+
+       * #29=IfcClosedShell((#104,#115,#131,#147,#163,#179))
+         On instance #29=IfcClosedShell((#104,...,#179)) the edge (-0.683012701892219,
+         -0.183012701892219, 1.0) -> (0.183012701892219, -0.683012701892219, 1.0) was
+         referenced 2 times
+
+       * #29=IfcClosedShell((#104,#115,#131,#147,#163,#179))
+         On instance #29=IfcClosedShell((#104,...,#179)) the edge (0.183012701892219,
+         -0.683012701892219, 1.0) -> (0.683012701892219, 0.183012701892219, 1.0) was
+         referenced 2 times
+
+       * #29=IfcClosedShell((#104,#115,#131,#147,#163,#179))
+         On instance #29=IfcClosedShell((#104,...,#179)) the edge (0.5, -0.5, 0.0) ->
+         (-0.5, -0.5, 0.0) was referenced 2 times
+
+       * #29=IfcClosedShell((#104,#115,#131,#147,#163,#179))
+         On instance #29=IfcClosedShell((#104,...,#179)) the edge (0.5, 0.5, 0.0) ->
+         (0.5, -0.5, 0.0) was referenced 2 times
+
+       * #29=IfcClosedShell((#104,#115,#131,#147,#163,#179))
+         On instance #29=IfcClosedShell((#104,...,#179)) the edge (0.683012701892219,
+         0.183012701892219, 1.0) -> (-0.183012701892219, 0.683012701892219, 1.0) was
+         referenced 2 times
+```
diff --git a/docs/dev/index.md b/docs/dev/index.md
@@ -0,0 +1,21 @@
+# Developer Guide
+
+```{include} validate_readme.md
+:heading-offset: 1
+```
+
+```{include} ifc_gherkin_rules_readme.md
+:heading-offset: 1
+```
+
+```{include} rule_details.md
+:heading-offset: 1
+```
+
+```{include} functional_parts.md
+:heading-offset: 1
+```
+
+```{include} gherkin_deep_dive.md
+:heading-offset: 1
+```