Gittes-archive/new-horizons
2
0
Fork 0
mirror of https://github.com/Outer-Wilds-New-Horizons/new-horizons.git synced 2025-12-11 20:15:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update Documentation Site (#54)

Browse Source 
* Add Bootstrap Extension

* Rename main.yml

* Artifact Upload

* Fix Bootstrap Reference Error

* BootstrapTreeProcessor

* getiterator removed

* keys function

* Style Images

* Update docs_build.yml

* Added Meta Files

* Template Get

* Fix Page Ref

* Update BASE_URL

* Sort Schemas

* Add Sitemaps

* Add favicons, open-graph, and setup guide

* Update Setup.md

* Update .gitignore

* Update Setup.md
This commit is contained in:
Ben C 2022-03-03 17:08:06 -08:00 committed by GitHub
parent 677363f5fe
commit 61cdb1b9f5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
39 changed files with 274 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.github/workflows/docs_build.yml vendored
View File

@ -8,6 +8,15 @@ on:
- NewHorizons/*schema*.json - NewHorizons/*schema*.json
workflow_dispatch: workflow_dispatch:
inputs:
relative_path:
description: "Path to set for relative files, set to a blank string for local builds"
required: false
default: "/"
env:
OUT_DIR: ${{ github.events.inputs.relative_path }}
BASE_URL: https://nh.outerwildsmods.com/
jobs: jobs:
build: build:

12
.gitignore vendored
View File

@ -396,7 +396,7 @@ FodyWeavers.xsd
# JetBrains Rider # JetBrains Rider
*.sln.iml *.sln.iml
.idea .idea/
packages packages
.vs .vs
@ -405,9 +405,9 @@ obj
zip zip
*.zip *.zip
*/Build/* */Build/**
.idea/ NewHorizons/Properties/**
docs/out/*
docs/schemas/*
NewHorizons/Properties/* # Docs
docs/out/**
docs/content/schemas/**

47
docs/Setup.md Normal file
View File

@ -0,0 +1,47 @@
# Setup to build docs
## Requirements
- Python 3.10
## Clone the repo
Clone the entire repo and navigate to the docs folder
```shell
git clone https://github.com/xen-42/outer-wilds-new-horizons
cd outer-wilds-new-horizons/docs
```
## Setup Pipenv
Install pipenv if you haven't already
```shell
pip install --user pipenv
```
Install dependencies
```shell
pipenv install
```
## Environment Variables
- OUT_DIR: Path to put before all links and static files, see below for recommended values
- Production: "/"
- Local Build: "" (set as empty string)
- PyCharm Development Server: "/outer-wilds-new-horizons/docs/out/"
- BASE_URL: Base url of the website we're hosting on
- Local: Leave blank
- Local (but wanting to test open-graph/twitter): "https://nh.outerwildsmods.com/"
- Production: "https://nh.outerwildsmods.com/"
## Copy Schemas
Create a folder called `schemas` in the content folder and copy all schemas to generate into it, make sure not to add this folder to git.
Production build automatically copies over schemas.
## Generating
Run `generate.py` with pipenv
```shell
pipenv run python generate.py
```
## Opening
- Production: Go to the site
- Local: Open `out/index.html`
- PyCharm Development Server: Right click `out/index.html` -> Open In -> Browser -> Default

15
docs/content/base/base.jinja2
View File

@ -7,10 +7,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html lang="en"> <html lang="en">
<head> <head>
<meta charset="UTF-8"> {% if dumb %}
<meta http-equiv="X-UA-Compatible" content="IE=edge"> {% include "meta.jinja2" %}
<meta name="viewport" content="width=device-width, initial-scale=1.0"> {% else %}
<title>New Horizons Documentation | {{ page.title|title }}</title> {% include "base/meta.jinja2" %}
{% endif %}
<link href="https://bootswatch.com/5/darkly/bootstrap.min.css" <link href="https://bootswatch.com/5/darkly/bootstrap.min.css"
crossorigin="anonymous" rel="stylesheet"> crossorigin="anonymous" rel="stylesheet">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.8.1/font/bootstrap-icons.css"> <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.8.1/font/bootstrap-icons.css">
@ -24,8 +25,10 @@
<header> <header>
<nav class="navbar navbar-expand-lg navbar-dark bg-dark mb-2"> <nav class="navbar navbar-expand-lg navbar-dark bg-dark mb-2">
<div class="container-fluid"> <div class="container-fluid">
<a class="navbar-brand" href="{{ 'home'|route }}">New Horizons</a> <a class="navbar-brand" href="{{ 'home'|route }}" aria-label="Home">
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" <img width="29" height="29" src="{{ "fav/favicon-96x96.png"|static }}" alt="New Horizons Logo" class="d-inline-block align-text-top me-2"/>
New Horizons</a>
<button class="navbar-toggler align-text-middle" type="button" data-bs-toggle="collapse"
data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent"
aria-expanded="false" aria-label="Toggle navigation"> aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span> <span class="navbar-toggler-icon"></span>

61
docs/content/base/meta.jinja2 Normal file
View File

@ -0,0 +1,61 @@
{# Macros #}
{% macro og(name, content) %}<meta property="og:{{ name }}" content="{{ content }}"/>{% endmacro %}
{% macro tw(name, content) %}<meta name="twitter:{{ name }}" content="{{ content }}"/>{% endmacro %}
{% macro fav(filename) %}{{ ("fav/" + filename)|static }}{% endmacro %}
{# Variable Declarations #}
{% if page.title|lower == 'home' %}
{% set title="New Horizons Documentation" %}
{% else %}
{% set title="New Horizons Documentation | " + page.title|title %}
{% endif %}
{% set desc="Documentation for creating planets with the New Horizons mod for Outer Wilds" %}
{% if page.description %}
{% set desc=page.description %}
{% endif %}
{% set img="images/home/home_logo.png"|static|full_url %}
{% set theme_color="#222222" %}
{# Meta Info #}
<meta charset="UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<title>{{ title }}</title>
<meta name="keywords" content="New Horizons, Outer Wilds, Modding, C#, Unity" />
<meta name="description" content="{{ desc }}"/>
{# OpenGraph Info #}
{{ og("type", "website") }}
{{ og("title", title) }}
{{ og("description", desc) }}
{{ og("url", page.title|route|full_url) }}
{{ og("image", img) }}
{{ og("image:alt", desc) }}
{# Twitter Info #}
{{ tw("title", title) }}
{{ tw("description", desc) }}
{{ tw("card", "summary_large_image") }}
{{ tw("image", img) }}
{# Favicons #}
<link rel="apple-touch-icon" sizes="57x57" href="{{ fav('apple-icon-57x57.png') }}">
<link rel="apple-touch-icon" sizes="60x60" href="{{ fav('apple-icon-60x60.png') }}">
<link rel="apple-touch-icon" sizes="72x72" href="{{ fav('apple-icon-72x72.png') }}">
<link rel="apple-touch-icon" sizes="76x76" href="{{ fav('apple-icon-76x76.png') }}">
<link rel="apple-touch-icon" sizes="114x114" href="{{ fav("apple-icon-114x114.png") }}">
<link rel="apple-touch-icon" sizes="120x120" href="{{ fav("apple-icon-120x120.png") }}">
<link rel="apple-touch-icon" sizes="144x144" href="{{ fav("apple-icon-144x144.png") }}">
<link rel="apple-touch-icon" sizes="152x152" href="{{ fav("apple-icon-152x152.png") }}">
<link rel="apple-touch-icon" sizes="180x180" href="{{ fav("apple-icon-180x180.png") }}">
<link rel="icon" type="image/png" sizes="192x192" href="{{ fav("android-icon-192x192.png") }}">
<link rel="icon" type="image/png" sizes="32x32" href="{{ fav("favicon-32x32.png") }}">
<link rel="icon" type="image/png" sizes="96x96" href="{{ fav("favicon-96x96.png") }}">
<link rel="icon" type="image/png" sizes="16x16" href="{{ fav("favicon-16x16.png") }}">
<link rel="manifest" href="{{ "manifest.json"|static }}">
<meta name="msapplication-config" content="{{ "fav/browserconfig.xml"|static }}" />
<meta name="msapplication-TileColor" content="{{ theme_color }}">
<meta name="msapplication-TileImage" content="{{ fav("ms-icon-144x144.png") }}">
<meta name="theme-color" data-react-helmet="true" content="{{ theme_color }}">

11
docs/content/browserconfig.jinja2 Normal file
View File

@ -0,0 +1,11 @@
<?xml version="1.0" encoding="utf-8"?>
<browserconfig>
<msapplication>
<tile>
<square70x70logo src="{{ "fav/ms-icon-70x70.png"|static }}"/>
<square150x150logo src="{{ "fav/ms-icon-150x150.png"|static }}"/>
<square310x310logo src="{{ "fav/ms-icon-70x70.png"|static }}"/>
<TileColor>#222222</TileColor>
</tile>
</msapplication>
</browserconfig>

4
docs/content/robots.jinja2 Normal file
View File

@ -0,0 +1,4 @@
User-Agent: *
Allow: /
Sitemap: {{ "/sitemap.xml"|full_url }}

11
docs/content/sitemap.jinja2 Normal file
View File

@ -0,0 +1,11 @@
<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.sitemaps.org/schemas/sitemap/0.9 http://www.sitemaps.org/schemas/sitemap/0.9/sitemap.xsd">
{% for item in content %}
<url>
<loc>{{ item.out_path|string|replace('\\', '/')|full_url }}</loc>
<priority>{{ item.sort_priority / 100 }}</priority>
</url>
{% endfor %}
</urlset>

BIN
docs/content/static/fav/android-icon-144x144.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/content/static/fav/android-icon-192x192.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
docs/content/static/fav/android-icon-36x36.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.6 KiB

BIN
docs/content/static/fav/android-icon-48x48.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.7 KiB

BIN
docs/content/static/fav/android-icon-72x72.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
docs/content/static/fav/android-icon-96x96.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.5 KiB

BIN
docs/content/static/fav/apple-icon-114x114.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 12 KiB

BIN
docs/content/static/fav/apple-icon-120x120.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB

BIN
docs/content/static/fav/apple-icon-144x144.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/content/static/fav/apple-icon-152x152.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/content/static/fav/apple-icon-180x180.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 23 KiB

BIN
docs/content/static/fav/apple-icon-57x57.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.6 KiB

BIN
docs/content/static/fav/apple-icon-60x60.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.9 KiB

BIN
docs/content/static/fav/apple-icon-72x72.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.3 KiB

BIN
docs/content/static/fav/apple-icon-76x76.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.9 KiB

BIN
docs/content/static/fav/apple-icon-precomposed.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

BIN
docs/content/static/fav/apple-icon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

BIN
docs/content/static/fav/favicon-16x16.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.3 KiB

BIN
docs/content/static/fav/favicon-32x32.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.3 KiB

BIN
docs/content/static/fav/favicon-96x96.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 9.5 KiB

BIN
docs/content/static/fav/favicon.ico Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

49
docs/content/static/fav/manifest.json Normal file
View File

@ -0,0 +1,49 @@
{
"$schema": "https://json.schemastore.org/web-manifest-combined.json",
"name": "New Horizons Docs",
"short_name": "NH Docs",
"categories": ["games", "utilities"],
"start_url": ".",
"theme_color": "#333333",
"background_color": "#222222",
"lang": "en-US",
"description": "Documentation for creating planets with the New Horizons mod for Outer Wilds",
"icons": [
{
"src": "/fav/android-icon-36x36.png",
"sizes": "36x36",
"type": "image/png",
"density": "0.75"
},
{
"src": "/fav/android-icon-48x58.png",
"sizes": "48x48",
"type": "image/png",
"density": "1.0"
},
{
"src": "/fav/android-icon-72x72.png",
"sizes": "72x72",
"type": "image/png",
"density": "1.5"
},
{
"src": "/fav/android-icon-96x96.png",
"sizes": "96x96",
"type": "image/png",
"density": "2.0"
},
{
"src": "/fav/android-icon-144x144.png",
"sizes": "144x144",
"type": "image/png",
"density": "3.0"
},
{
"src": "/fav/android-icon-192x192.png",
"sizes": "192x192",
"type": "image/png",
"density": "4.0"
}
]
}

BIN
docs/content/static/fav/ms-icon-144x144.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 17 KiB

BIN
docs/content/static/fav/ms-icon-150x150.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 18 KiB

BIN
docs/content/static/fav/ms-icon-310x310.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 49 KiB

BIN
docs/content/static/fav/ms-icon-70x70.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.1 KiB

2
docs/content/static/robots.txt
View File

@ -1,2 +0,0 @@
User-agent: *
Allow: /

37
docs/generate.py
View File

@ -7,10 +7,12 @@ from markupsafe import Markup
from json_schema_for_humans.generate import GenerationConfiguration from json_schema_for_humans.generate import GenerationConfiguration
from markdown import Markdown from markdown import Markdown
from lib.BootstrapExtension import BootstrapExtension
from lib.Schema import Schema from lib.Schema import Schema
from lib.Page import Page from lib.Page import Page
OUT_DIR = os.getenv("OUT_DIR", "/") OUT_DIR = os.getenv("OUT_DIR", "/")
BASE_URL = os.getenv("BASE_URL", "")
if Path("out/").exists(): if Path("out/").exists():
rmtree("out/", ignore_errors=True) rmtree("out/", ignore_errors=True)
@ -24,7 +26,7 @@ env = Environment(
) )
markdown_settings = { markdown_settings = {
'extensions': ['extra', 'meta'] 'extensions': ['extra', 'meta', BootstrapExtension()]
} }
schema_settings = GenerationConfiguration(custom_template_path="content/base/schema_base.jinja2") schema_settings = GenerationConfiguration(custom_template_path="content/base/schema_base.jinja2")
@ -42,6 +44,7 @@ schemas_paths = Path("content/schemas").glob("**/*.json")
router = {} router = {}
env.filters['route'] = lambda title: router.get(title.lower(), "#") env.filters['route'] = lambda title: router.get(title.lower(), "#")
env.filters['full_url'] = lambda relative: BASE_URL + (relative[1:] if relative[0] == "/" else relative)
pages = [] pages = []
schemas = [] schemas = []
@ -56,14 +59,32 @@ for schema_path in schemas_paths:
router[new_schema.title.lower()] = OUT_DIR + "schemas/" + str(new_schema.out_path.relative_to("out/schemas/")) router[new_schema.title.lower()] = OUT_DIR + "schemas/" + str(new_schema.out_path.relative_to("out/schemas/"))
schemas.append(new_schema) schemas.append(new_schema)
router['home'] = OUT_DIR content = pages + schemas
if OUT_DIR != "":
router['home'] = OUT_DIR
pages.sort(key=lambda p: p.sort_priority, reverse=True) pages.sort(key=lambda p: p.sort_priority, reverse=True)
schemas.sort(key=lambda s: s.title)
for page in pages:
print(page.in_path, "->", page.out_path)
page.render(page=page, pages=pages, schemas=schemas)
for schema in schemas: def log_build(in_path, out_path):
print(schema.in_path, "->", schema.out_path) print("Building:", str(in_path), "->", str(out_path))
schema.render(page=schema, pages=pages, schemas=schemas)
def build_meta(in_path, out_path):
log_build(in_path, out_path)
meta_template = env.get_template(str(in_path.relative_to("content/")))
with Path("out/", out_path).open(mode="w+", encoding="utf-8") as file:
file.write(meta_template.render(content=content))
print("Building Meta Files")
build_meta(Path("content/sitemap.jinja2"), Path("sitemap.xml"))
build_meta(Path("content/robots.jinja2"), Path("robots.txt"))
build_meta(Path("content/browserconfig.jinja2"), Path("fav/browserconfig.xml"))
print ("Building Pages")
for item in content:
log_build(item.in_path, item.out_path)
item.render(page=item, pages=pages, schemas=schemas)

33
docs/lib/BootstrapExtension.py Normal file
View File

@ -0,0 +1,33 @@
from markdown import Extension
from markdown.treeprocessors import Treeprocessor
class BootstrapExtension(Extension):
def extendMarkdown(self, md, md_globals):
md.registerExtension(self)
self.processor = BootstrapTreeProcessor()
self.processor.md = md
self.processor.config = self.getConfigs()
md.treeprocessors.add('bootstrap', self.processor, '_end')
classes = {
'img': "img-fluid rounded mx-auto d-flex",
'table': "table-striped"
}
def process(node):
if node.tag in classes.keys():
node.set("class", classes[node.tag])
for child in node:
process(child)
class BootstrapTreeProcessor(Treeprocessor):
def run(self, node):
for child in node:
process(child)
return node

4
docs/lib/Page.py
View File

@ -11,6 +11,7 @@ class Page:
in_path: Path in_path: Path
out_path: Path out_path: Path
title: str title: str
description: str | None
env: Environment env: Environment
def __init__(self, path, environment, options): def __init__(self, path, environment, options):
@ -19,8 +20,9 @@ class Page:
md = Markdown(**options) md = Markdown(**options)
with path.open() as file: with path.open() as file:
md.convert(file.read()) md.convert(file.read())
self.sort_priority = int(md.Meta.get('sort-priority', '0')[0]) self.sort_priority = int(md.Meta.get('sort-priority', '20')[0])
self.title = md.Meta.get('title', (path.stem,))[0] self.title = md.Meta.get('title', (path.stem,))[0]
self.description = md.Meta.get('description', None)
outfile: Path outfile: Path
try: try:
outfile = Path("out/", path.relative_to(Path("content/pages/")).parent, outfile = Path("out/", path.relative_to(Path("content/pages/")).parent,

3
docs/lib/Schema.py
View File

@ -17,12 +17,13 @@ class Schema(Page):
config: GenerationConfiguration config: GenerationConfiguration
def __init__(self, path, env, options): def __init__(self, path, env, options):
self.sort_priority = 0 self.sort_priority = 10
self.in_path = path self.in_path = path
self.config = options self.config = options
self.env = env self.env = env
with path.open() as file: with path.open() as file:
self.title = json.load(file).get('title', path.stem) self.title = json.load(file).get('title', path.stem)
self.description = "Schema for a " + self.title + " in New Horizons"
self.out_path = Path('out/schemas/', self.in_path.relative_to(Path("content/schemas/")).with_name(self.title.replace(" ", "_").lower()).with_suffix(".html")) self.out_path = Path('out/schemas/', self.in_path.relative_to(Path("content/schemas/")).with_name(self.title.replace(" ", "_").lower()).with_suffix(".html"))
def render(self, **options): def render(self, **options):