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
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:
build:

12
.gitignore vendored
View File

@ -396,7 +396,7 @@ FodyWeavers.xsd
# JetBrains Rider
*.sln.iml
.idea
.idea/
packages
.vs
@ -405,9 +405,9 @@ obj
zip
*.zip
*/Build/*
.idea/
docs/out/*
docs/schemas/*
*/Build/**
NewHorizons/Properties/**
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>
<html lang="en">
<head>
<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>New Horizons Documentation | {{ page.title|title }}</title>
{% if dumb %}
{% include "meta.jinja2" %}
{% else %}
{% include "base/meta.jinja2" %}
{% endif %}
<link href="https://bootswatch.com/5/darkly/bootstrap.min.css"
crossorigin="anonymous" rel="stylesheet">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.8.1/font/bootstrap-icons.css">
@ -24,8 +25,10 @@
<header>
<nav class="navbar navbar-expand-lg navbar-dark bg-dark mb-2">
<div class="container-fluid">
<a class="navbar-brand" href="{{ 'home'|route }}">New Horizons</a>
<button class="navbar-toggler" type="button" data-bs-toggle="collapse"
<a class="navbar-brand" href="{{ 'home'|route }}" aria-label="Home">
<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"
aria-expanded="false" aria-label="Toggle navigation">
<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 markdown import Markdown
from lib.BootstrapExtension import BootstrapExtension
from lib.Schema import Schema
from lib.Page import Page
OUT_DIR = os.getenv("OUT_DIR", "/")
BASE_URL = os.getenv("BASE_URL", "")
if Path("out/").exists():
rmtree("out/", ignore_errors=True)
@ -24,7 +26,7 @@ env = Environment(
)
markdown_settings = {
'extensions': ['extra', 'meta']
'extensions': ['extra', 'meta', BootstrapExtension()]
}
schema_settings = GenerationConfiguration(custom_template_path="content/base/schema_base.jinja2")
@ -42,6 +44,7 @@ schemas_paths = Path("content/schemas").glob("**/*.json")
router = {}
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 = []
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/"))
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)
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:
print(schema.in_path, "->", schema.out_path)
schema.render(page=schema, pages=pages, schemas=schemas)
def log_build(in_path, out_path):
print("Building:", str(in_path), "->", str(out_path))
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
out_path: Path
title: str
description: str | None
env: Environment
def __init__(self, path, environment, options):
@ -19,8 +20,9 @@ class Page:
md = Markdown(**options)
with path.open() as file:
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.description = md.Meta.get('description', None)
outfile: Path
try:
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
def __init__(self, path, env, options):
self.sort_priority = 0
self.sort_priority = 10
self.in_path = path
self.config = options
self.env = env
with path.open() as file:
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"))
def render(self, **options):