Sets up a simple documentation website for mllint, built with Hugo us…

…ing PaperMod theme. Already contains the information from the ReadMe, all it needs now are auto-generated rule & category documentations.
bvobart · Jul 25, 2021 · 63f21ff · 63f21ff
1 parent a06595c
commit 63f21ff
Show file tree

Hide file tree

Showing 15 changed files with 496 additions and 3 deletions.
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "docs/gh-pages/themes/PaperMod"]
+	path = docs/gh-pages/themes/PaperMod
+	url = https://github.com/adityatelange/hugo-PaperMod.git
diff --git a/ReadMe.md b/ReadMe.md
@@ -25,7 +25,7 @@
 
 `mllint` is created during my MSc thesis in Computer Science at the Software Engineering Research Group ([SERG](https://se.ewi.tudelft.nl/)) at [TU Delft](https://tudelft.nl/) and [ING](https://www.ing.com/)'s [AI for FinTech Research Lab](https://se.ewi.tudelft.nl/ai4fintech/) on the topic of _Code Quality and Software Engineering for Machine Learning projects_
 
-<p align="center"><img src="./docs/example-run.svg"></p>
+<p align="center"><img src="./docs/gh-pages/static/example-run.svg"></p>
 
 > See [`docs/example-report.md`](docs/example-report.md) to view the report generated for this example project.
 >
@@ -62,9 +62,9 @@ pip install --upgrade mllint[tools]
 
 ### Docker
 
-There are also `mllint` Docker containers available on [Docker Hub](https://hub.docker.com/r/bvobart/mllint) at `bvobart/mllint` for Python 3.6, 3.7, 3.8 and 3.9. They require that you mount the folder with your project onto the container as a volume on `/app`.
+There are also `mllint` Docker containers available on [Docker Hub](https://hub.docker.com/r/bvobart/mllint) at `bvobart/mllint` for Python 3.6, 3.7, 3.8 and 3.9. These may particularly be helpful when running `mllint` in CI environments, such as Gitlab CI or Github Actions. See the Docker Hub for a full list of available tags that can be used.
 
-Here is an example of how to use this Docker container, assuming that your project is in the current folder. Replace `$(pwd)` with the full path to your project folder if it is somewhere else.
+The Docker containers require that you mount the folder with your project onto the container as a volume on `/app`. Here is an example of how to use this Docker container, assuming that your project is in the current folder. Replace `$(pwd)` with the full path to your project folder if it is somewhere else.
 
 ```sh
 docker run -it --rm -v $(pwd):/app bvobart/mllint:latest

diff --git a/docs/gh-pages/assets/css/extended/highlightjs.css b/docs/gh-pages/assets/css/extended/highlightjs.css
@@ -0,0 +1,113 @@
+/*
+ * Visual Studio 2015 dark style
+ * Author: Nicolas LLOBERA <[email protected]>
+ * Sourced from: https://github.com/highlightjs/highlight.js/blob/main/src/styles/vs2015.css
+ */
+
+ .hljs {
+  background: #1E1E1E;
+  color: #DCDCDC;
+}
+
+.hljs-keyword,
+.hljs-literal,
+.hljs-symbol,
+.hljs-name {
+  color: #569CD6;
+}
+.hljs-link {
+  color: #569CD6;
+  text-decoration: underline;
+}
+
+.hljs-built_in,
+.hljs-type {
+  color: #4EC9B0;
+}
+
+.hljs-number,
+.hljs-class {
+  color: #B8D7A3;
+}
+
+.hljs-string,
+.hljs-meta .hljs-string {
+  color: #D69D85;
+}
+
+.hljs-regexp,
+.hljs-template-tag {
+  color: #9A5334;
+}
+
+.hljs-subst,
+.hljs-function,
+.hljs-title,
+.hljs-params,
+.hljs-formula {
+  color: #DCDCDC;
+}
+
+.hljs-comment,
+.hljs-quote {
+  color: #57A64A;
+  font-style: italic;
+}
+
+.hljs-doctag {
+  color: #608B4E;
+}
+
+.hljs-meta,
+.hljs-meta .hljs-keyword,
+
+.hljs-tag {
+  color: #9B9B9B;
+}
+
+.hljs-variable,
+.hljs-template-variable {
+  color: #BD63C5;
+}
+
+.hljs-attr,
+.hljs-attribute {
+  color: #9CDCFE;
+}
+
+.hljs-section {
+  color: gold;
+}
+
+.hljs-emphasis {
+  font-style: italic;
+}
+
+.hljs-strong {
+  font-weight: bold;
+}
+
+/*.hljs-code {
+  font-family:'Monospace';
+}*/
+
+.hljs-bullet,
+.hljs-selector-tag,
+.hljs-selector-id,
+.hljs-selector-class,
+.hljs-selector-attr,
+.hljs-selector-pseudo {
+  color: #D7BA7D;
+}
+
+.hljs-addition {
+  background-color: #144212;
+  display: inline-block;
+  width: 100%;
+}
+
+.hljs-deletion {
+  background-color: #600;
+  display: inline-block;
+  width: 100%;
+}
diff --git a/docs/gh-pages/assets/css/extended/tweaks.css b/docs/gh-pages/assets/css/extended/tweaks.css
@@ -0,0 +1,4 @@
+:root {
+  --nav-width: 1200px;
+  --main-width: 1200px;
+}
diff --git a/docs/gh-pages/config.yml b/docs/gh-pages/config.yml
@@ -0,0 +1,169 @@
+title: "mllint — Linter for Machine Learning projects"
+baseURL: "http://bvobart.github.io/mllint"
+theme: "PaperMod"
+
+enableInlineShortcodes: true
+enableRobotsTXT: true
+buildDrafts: false
+buildFuture: false
+buildExpired: false
+enableEmoji: true
+# googleAnalytics: UA-123-45
+
+minify:
+    disableXML: true
+    # minifyOutput: true
+
+languages:
+    en:
+        languageName: "English"
+        weight: 1
+        menu:
+            main:
+                - name: About
+                  url: about/
+                  weight: 9
+                - name: Docs
+                  url: docs/
+                  weight: 10
+                - name: Installation
+                  url: docs/installation/
+                  weight: 11
+                - name: Usage
+                  url: docs/usage/
+                  weight: 11
+                - name: Search
+                  url: search/
+                  weight: 20
+
+outputs:
+    home:
+        - HTML
+        - RSS
+        - JSON
+
+params:
+    env: production # to enable google analytics, opengraph, twitter-cards and schema.
+    description: "mllint — Linter for Machine Learning projects - https://github.com/adityatelange/hugo-PaperMod"
+    author: Bart van Oort (bvobart)
+
+    defaultTheme: dark
+    # disableThemeToggle: true
+    # ShowShareButtons: true
+    ShowReadingTime: true
+    # disableSpecial1stPost: true
+    displayFullLangName: true
+    ShowPostNavLinks: true
+    ShowBreadCrumbs: true
+    ShowCodeCopyButtons: true
+    ShowToc: true
+    # comments: false
+    images: ["example-run.svg"]
+
+    homeInfoParams:
+        Title: "mllint — Linter for Machine Learning projects"
+        Content: |
+            `mllint` is a command-line utility to evaluate the technical quality of Machine Learning (ML) and Artificial Intelligence (AI) projects written in Python by analysing the project's source code, data and configuration of supporting tools.
+            <br />
+            <br />
+            `mllint` aims to ...
+            <br />
+            > ... help data scientists and ML engineers in creating and maintaining production-grade ML and AI projects, both on their own personal computers as well as on CI.
+
+            > ... help ML practitioners inexperienced with Software Engineering (SE) techniques explore and make effective use of battle-hardended SE for ML tools in the Python ecosystem.
+
+            > ... help ML project managers assess the quality of their ML and AI projects and receive recommendations on what aspects of their projects they should focus on improving.
+
+            `mllint` does this by measuring the project's adherence to ML best practices, as collected and deduced from [SE4ML](https://se-ml.github.io/) and Google's [Rules for ML](https://developers.google.com/machine-learning/guides/rules-of-ml). Note that these best practices are rather high-level, while `mllint` aims to give practical, down-to-earth advice to its users. `mllint` may therefore be somewhat opinionated, as it tries to advocate specific tools to best fit these best practices. However, `mllint` aims to only recommend open-source tooling and publically verifiable practices. Feedback is of course always welcome!
+            <br />
+            <br />
+            `mllint` is created during my MSc thesis in Computer Science at the Software Engineering Research Group ([SERG](https://se.ewi.tudelft.nl/)) at [TU Delft](https://tudelft.nl/) and [ING](https://www.ing.com/)'s [AI for FinTech Research Lab](https://se.ewi.tudelft.nl/ai4fintech/) on the topic of _Code Quality and Software Engineering for Machine Learning projects_
+            <br />
+            <br />
+            
+            > See also the [`mllint-example-projects`](https://github.com/bvobart/mllint-example-projects) repository to explore the reports of an example project using `mllint` to measure and improve its project quality over several iterations.
+            
+            > See [this `example-report.md`](https://github.com/bvobart/mllint/blob/main/docs/example-report.md) to view the report generated for the example project in the demo below.
+            
+            <p align="center"><img src="example-run.svg" alt="Example run of mllint"></p>
+
+
+    socialIcons:
+        - name: github
+          url: "https://github.com/bvobart/mllint"
+
+    # editPost:
+    #     URL: "https://github.com/adityatelange/hugo-PaperMod/tree/exampleSite/content"
+    #     Text: "Suggest Changes" # edit text
+    #     appendFilePath: true # to append file path to Edit link
+
+    # label:
+    #     text: "Home"
+    #     icon: icon.png
+    #     iconHeight: 35
+
+    # analytics:
+    #     google:
+    #         SiteVerificationTag: "XYZabc"
+
+    # assets:
+    #     favicon: "<link / abs url>"
+    #     favicon16x16: "<link / abs url>"
+    #     favicon32x32: "<link / abs url>"
+    #     apple_touch_icon: "<link / abs url>"
+    #     safari_pinned_tab: "<link / abs url>"
+
+    # cover:
+    #     hidden: true # hide everywhere but not in structured data
+    #     hiddenInList: true # hide on list pages and home
+    #     hiddenInSingle: true # hide on single page
+
+    # fuseOpts:
+    #     isCaseSensitive: false
+    #     shouldSort: true
+    #     location: 0
+    #     distance: 1000
+    #     threshold: 0.4
+    #     minMatchCharLength: 0
+    #     keys: ["title", "permalink", "summary", "content"]
+
+# taxonomies:
+#     category: categories
+#     tag: tags
+#     series: series
+
+markup:
+    goldmark:
+        renderer:
+            unsafe: true
+#     highlight:
+#         # anchorLineNos: true
+#         codeFences: true
+#         guessSyntax: true
+#         lineNos: true
+#         # noClasses: false
+#         style: monokai
+
+privacy:
+    vimeo:
+        disabled: false
+        simple: true
+
+    twitter:
+        disabled: false
+        enableDNT: true
+        simple: true
+
+    instagram:
+        disabled: false
+        simple: true
+
+    youtube:
+        disabled: false
+        privacyEnhanced: true
+
+services:
+    instagram:
+        disableInlineCSS: true
+    twitter:
+        disableInlineCSS: true
diff --git a/docs/gh-pages/content/about.md b/docs/gh-pages/content/about.md
@@ -0,0 +1,7 @@
+---
+title: "About"
+# description: ""
+summary: ""
+---
+
+Something something mllint was the product of my MSc thesis and this is how it came to be :)
diff --git a/docs/gh-pages/content/docs/_index.md b/docs/gh-pages/content/docs/_index.md
@@ -0,0 +1,10 @@
+---
+title: "Documentation"
+description: "Documentation on the usage of mllint and its linting rules."
+---
+
+# Plopkoek
+
+Hallo :)
+
+Pindakaas
diff --git a/docs/gh-pages/content/docs/categories/_index.md b/docs/gh-pages/content/docs/categories/_index.md
@@ -0,0 +1,7 @@
+---
+title: "Categories"
+description: "mllint analyses your ML project on adherence to software quality standards based on several categories. Find out more about each category entails and what rules they contain here."
+weight: 8
+---
+
+`mllint` analyses your ML project on adherence to software quality standards based on several categories. Find out more about each category entails and what rules they contain here.
diff --git a/docs/gh-pages/content/docs/configuration.md b/docs/gh-pages/content/docs/configuration.md
@@ -0,0 +1,54 @@
+---
+title: "Configuration"
+description: "Shows `mllint` can be configured, including YAML and TOML examples"
+weight: 7
+# summary: ""
+---
+
+`mllint` can be configured either using a `.mllint.yml` file or through the project's `pyproject.toml`. This allows you to:
+- selectively disable specific linting rules or categories using their slug
+- define custom linting rules
+- configure specific settings for various linting rules.
+
+See the code snippets and commands provided below for examples of such configuration files.
+
+### Commands
+
+To print `mllint`'s current configuration in YAML format, run (optionally providing the path to the project's folder):
+```sh
+mllint config
+```
+
+To print `mllint`'s default configuration in YAML format, run (unless there is a folder called `default` in the current directory):
+```sh
+mllint config default
+```
+
+To create a `.mllint.yml` file from `mllint`'s default configuration, run:
+```sh
+mllint config default -q > .mllint.yml
+```
+
+### YAML
+
+An example `.mllint.yml` that disables some rules looks as follows:
+
+```yaml
+rules:
+  disabled:
+    - version-control/code/git
+    - dependency-management/single
+```
+
+Similar to the `describe` command, this also matches partial slugs. So, to disable all rules regarding version controlling data, use `version-control/data`.
+
+### TOML
+
+If no `.mllint.yml` is found, `mllint` searches the project's `pyproject.toml` for a `[tool.mllint]` section. TOML has a slightly different syntax, but the structure is otherwise the same as the config in the YAML file. 
+
+An example `pyproject.toml` configuration of `mllint` is as follows. Note that it is identical to the YAML example above.
+
+```toml
+[tool.mllint.rules]
+disabled = ["version-control/code/git", "dependency-management/single"]
+```