From f48669ecf83a1a6b37f88ec1a39792caaa463f28 Mon Sep 17 00:00:00 2001 From: Yamithorn Date: Tue, 14 Dec 2021 10:52:20 -0500 Subject: [PATCH] Add in static site --- .github/workflows/docs.yml | 36 +++ .gitignore | 3 + docs/docfx.json | 40 +++ docs/package.json | 10 + .../material/partials/head.tmpl.partial | 21 ++ docs/templates/material/styles/main.css | 306 ++++++++++++++++++ docs/toc.js | 60 ++++ docs/toc.yml | 3 + 8 files changed, 479 insertions(+) create mode 100644 .github/workflows/docs.yml create mode 100644 docs/docfx.json create mode 100644 docs/package.json create mode 100644 docs/templates/material/partials/head.tmpl.partial create mode 100644 docs/templates/material/styles/main.css create mode 100644 docs/toc.js create mode 100644 docs/toc.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..5cdcf6a --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,36 @@ +name: Build and Deploy Documentation +on: + push: + branches: + - main + +jobs: + deploy-docs: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v2.3.5 + + - name: Parse Docs + uses: nikeee/docfx-action@v1.0.0 + with: + args: metadata docs/docfx.json + + - name: Setup Node + uses: actions/setup-node@v2 + with: + node-version: '14' + + - name: Transform ToC + run: cd docs && yarn && sudo node toc.js + + - name: Build Docs + uses: nikeee/docfx-action@v1.0.0 + with: + args: build docs/docfx.json + + - name: Deploy Docs + uses: JamesIves/github-pages-deploy-action@4.1.5 + with: + branch: gh-pages + folder: site/html \ No newline at end of file diff --git a/.gitignore b/.gitignore index 9694128..eadcc5d 100644 --- a/.gitignore +++ b/.gitignore @@ -351,3 +351,6 @@ MigrationBackup/ # Ionide (cross platform F# VS Code tools) working folder .ionide/ + +# docs +site/ \ No newline at end of file diff --git a/docs/docfx.json b/docs/docfx.json new file mode 100644 index 0000000..997bcd1 --- /dev/null +++ b/docs/docfx.json @@ -0,0 +1,40 @@ +{ + "metadata": [ + { + "src": [ + { + "files": ["**/Gossip.csproj"], + "exclude": ["**/bin/**", "**/obj/**"], + "src": "../" + } + ], + "dest": "../site/yml/api" + } + ], + "build": { + "content": [ + { + "files": [ "**/*.yml" ], + "src": "../site/yml/api", + "dest": "api" + }, + { + "files": [ + "*.md", + "toc.yml" + ] + } + ], + "template": [ + "default", + "templates/material" + ], + "globalMetadata": { + "_appTitle": "Gossip", + "_enableSearch": true + }, + "markdownEngineName": "markdig", + "dest": "../site/html", + "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ] + } +} \ No newline at end of file diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 0000000..fdb9b1d --- /dev/null +++ b/docs/package.json @@ -0,0 +1,10 @@ +{ + "name": "gossip-docs", + "description": "Documentation generator for the Gossip C# package", + "version": "1.0.0", + "author": "", + "dependencies": { + "js-yaml": "4.1.0" + }, + "license": "MIT" +} \ No newline at end of file diff --git a/docs/templates/material/partials/head.tmpl.partial b/docs/templates/material/partials/head.tmpl.partial new file mode 100644 index 0000000..eaac2fc --- /dev/null +++ b/docs/templates/material/partials/head.tmpl.partial @@ -0,0 +1,21 @@ +{{!Copyright (c) Oscar Vasquez. All rights reserved. Licensed under the MIT license. See LICENSE file in the project root for full license information.}} + + + + + {{#title}}{{title}}{{/title}}{{^title}}{{>partials/title}}{{/title}} {{#_appTitle}}| {{_appTitle}} {{/_appTitle}} + + + + {{#_description}}{{/_description}} + + + + + + + + {{#_noindex}}{{/_noindex}} + {{#_enableSearch}}{{/_enableSearch}} + {{#_enableNewTab}}{{/_enableNewTab}} + \ No newline at end of file diff --git a/docs/templates/material/styles/main.css b/docs/templates/material/styles/main.css new file mode 100644 index 0000000..e21a08c --- /dev/null +++ b/docs/templates/material/styles/main.css @@ -0,0 +1,306 @@ +/* COLOR VARIABLES */ +:root { + --header-bg-color: #0d47a1; + --header-ft-color: #fff; + --highlight-light: #5e92f3; + --highlight-dark: #003c8f; + --accent-dim: #e0e0e0; + --accent-super-dim: #f3f3f3; + --font-color: #34393e; + --card-box-shadow: 0 1px 2px 0 rgba(61, 65, 68, 0.06), 0 1px 3px 1px rgba(61, 65, 68, 0.16); + --search-box-shadow: 0 1px 2px 0 rgba(41, 45, 48, 0.36), 0 1px 3px 1px rgba(41, 45, 48, 0.46); + --transition: 350ms; +} + +body { + color: var(--font-color); + font-family: "Roboto", sans-serif; + line-height: 1.5; + font-size: 16px; + -ms-text-size-adjust: 100%; + -webkit-text-size-adjust: 100%; + word-wrap: break-word; +} + +/* HIGHLIGHT COLOR */ + +button, +a { + color: var(--highlight-dark); + cursor: pointer; +} + +button:hover, +button:focus, +a:hover, +a:focus { + color: var(--highlight-light); + text-decoration: none; +} + +.toc .nav > li.active > a { + color: var(--highlight-dark); +} + +.toc .nav > li.active > a:hover, +.toc .nav > li.active > a:focus { + color: var(--highlight-light); +} + +.pagination > .active > a { + background-color: var(--header-bg-color); + border-color: var(--header-bg-color); +} + +.pagination > .active > a, +.pagination > .active > a:focus, +.pagination > .active > a:hover, +.pagination > .active > span, +.pagination > .active > span:focus, +.pagination > .active > span:hover { + background-color: var(--highlight-light); + border-color: var(--highlight-light); +} + +/* HEADINGS */ + +h1 { + font-weight: 600; + font-size: 32px; +} + +h2 { + font-weight: 600; + font-size: 24px; + line-height: 1.8; +} + +h3 { + font-weight: 600; + font-size: 20px; + line-height: 1.8; +} + +h5 { + font-size: 14px; + padding: 10px 0px; +} + +article h1, +article h2, +article h3, +article h4 { + margin-top: 35px; + margin-bottom: 15px; +} + +article h4 { + padding-bottom: 8px; + border-bottom: 2px solid #ddd; +} + +/* NAVBAR */ + +.navbar-brand > img { + color: var(--header-ft-color); +} + +.navbar { + border: none; + /* Both navbars use box-shadow */ + -webkit-box-shadow: var(--card-box-shadow); + -moz-box-shadow: var(--card-box-shadow); + box-shadow: var(--card-box-shadow); +} + +.subnav { + border-top: 1px solid #ddd; + background-color: #fff; +} + +.navbar-inverse { + background-color: var(--header-bg-color); + z-index: 100; +} + +.navbar-inverse .navbar-nav > li > a, +.navbar-inverse .navbar-text { + color: var(--header-ft-color); + background-color: var(--header-bg-color); + border-bottom: 3px solid transparent; + padding-bottom: 12px; + transition: 350ms; +} + +.navbar-inverse .navbar-nav > li > a:focus, +.navbar-inverse .navbar-nav > li > a:hover { + color: var(--header-ft-color); + background-color: var(--header-bg-color); + border-bottom: 3px solid white; +} + +.navbar-inverse .navbar-nav > .active > a, +.navbar-inverse .navbar-nav > .active > a:focus, +.navbar-inverse .navbar-nav > .active > a:hover { + color: var(--header-ft-color); + background-color: var(--header-bg-color); + border-bottom: 3px solid white; +} + +.navbar-form .form-control { + border: 0; + border-radius: 4px; + box-shadow: var(--search-box-shadow); + transition:var(--transition); +} + +.navbar-form .form-control:hover { + background-color: var(--accent-dim); +} + +/* NAVBAR TOGGLED (small screens) */ + +.navbar-inverse .navbar-collapse, .navbar-inverse .navbar-form { + border: none; +} +.navbar-inverse .navbar-toggle { + box-shadow: var(--card-box-shadow); + border: none; +} + +.navbar-inverse .navbar-toggle:focus, +.navbar-inverse .navbar-toggle:hover { + background-color: var(--highlight-dark); +} + +/* SIDEBAR */ + +.toc .level1 > li { + font-weight: 400; +} + +.toc .nav > li > a { + color: var(--font-color); +} + +.sidefilter { + background-color: #fff; + border-left: none; + border-right: none; +} + +.sidefilter { + background-color: #fff; + border-left: none; + border-right: none; +} + +.toc-filter { + padding: 5px; + margin: 0; + box-shadow: var(--card-box-shadow); + transition:var(--transition); +} + +.toc-filter:hover { + background-color: var(--accent-super-dim); +} + +.toc-filter > input { + border: none; + background-color: inherit; + transition: inherit; +} + +.toc-filter > .filter-icon { + display: none; +} + +.sidetoc > .toc { + background-color: #fff; + overflow-x: hidden; +} + +.sidetoc { + background-color: #fff; + border: none; +} + +/* ALERTS */ + +.alert { + padding: 0px 0px 5px 0px; + color: inherit; + background-color: inherit; + border: none; + box-shadow: var(--card-box-shadow); +} + +.alert > p { + margin-bottom: 0; + padding: 5px 10px; +} + +.alert > ul { + margin-bottom: 0; + padding: 5px 40px; +} + +.alert > h5 { + padding: 10px 15px; + margin-top: 0; + text-transform: uppercase; + font-weight: bold; + border-radius: 4px 4px 0 0; +} + +.alert-info > h5 { + color: #1976d2; + border-bottom: 4px solid #1976d2; + background-color: #e3f2fd; +} + +.alert-warning > h5 { + color: #f57f17; + border-bottom: 4px solid #f57f17; + background-color: #fff3e0; +} + +.alert-danger > h5 { + color: #d32f2f; + border-bottom: 4px solid #d32f2f; + background-color: #ffebee; +} + +/* CODE HIGHLIGHT */ +pre { + padding: 9.5px; + margin: 0 0 10px; + font-size: 13px; + word-break: break-all; + word-wrap: break-word; + background-color: #fffaef; + border-radius: 4px; + border: none; + box-shadow: var(--card-box-shadow); +} + +/* STYLE FOR IMAGES */ + +.article .small-image { + margin-top: 15px; + box-shadow: var(--card-box-shadow); + max-width: 350px; +} + +.article .medium-image { + margin-top: 15px; + box-shadow: var(--card-box-shadow); + max-width: 550px; +} + +.article .large-image { + margin-top: 15px; + box-shadow: var(--card-box-shadow); + max-width: 700px; +} \ No newline at end of file diff --git a/docs/toc.js b/docs/toc.js new file mode 100644 index 0000000..60391dc --- /dev/null +++ b/docs/toc.js @@ -0,0 +1,60 @@ +/** + * Adapted from https://github.com/dotnet/docfx/issues/274#issuecomment-456168196 + */ + +var fs = require('fs'); +var yaml = require('js-yaml'); +var toc = yaml.load(fs.readFileSync('../site/yml/api/toc.yml')); + +var root = "Gossip"; +var namespaces = { + [root]: {} +}; + +for (var i = 0; i < toc.length; i++) { + var fullnamespace = toc[i].uid; + var splitnamespace = [root]; + if (fullnamespace != root) { + var subnamespace = fullnamespace.replace(root + '.', '').split('.'); + splitnamespace.push(...subnamespace); + } + + var parent = namespaces; + + for (var j = 0; j < splitnamespace.length; j++) { + var partialnamespace = splitnamespace[j]; + + if (parent[partialnamespace] == undefined) { + parent[partialnamespace] = {}; + } + parent = parent[partialnamespace]; + } + + if (parent.items == undefined) { + parent.items = toc[i].items; + } else { + parent.items.push(toc[i]); + } +} + +function recurse(obj, path = "") { + var items = []; + Object.keys(obj).forEach((e, i) => { + if (e != "items") { + var newPath; + if (path == "") { + newPath = e; + } else { + newPath = path + '.' + e; + } + var newObj = {uid: newPath, name: e, items: obj[e].items || []} + newObj.items.push(...recurse(obj[e], newPath)); + items.push(newObj); + } + }); + return items; +} + +var items = recurse(namespaces); + +fs.writeFileSync('../site/yml/api/toc.yml', yaml.dump(items)); \ No newline at end of file diff --git a/docs/toc.yml b/docs/toc.yml new file mode 100644 index 0000000..c180ad1 --- /dev/null +++ b/docs/toc.yml @@ -0,0 +1,3 @@ +- name: API Documentation + href: ../site/yml/api/ + homepage: ../site/yml/api/Gossip.yml \ No newline at end of file