Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
(GH-2) Use Docsy as template for all sites.
This is a mass rewrite of all docs sites.
- Loading branch information
1 parent
5db2748
commit ed0ddfb
Showing
158 changed files
with
5,596 additions
and
440 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,9 @@ | ||
resources/_gen | ||
public | ||
|
||
public/ | ||
resources/ | ||
node_modules/ | ||
tech-doc-hugo | ||
tmp/ | ||
|
||
lingua-pupuli/static/editor-services | ||
lingua-pupuli/static/editor-syntax |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
[submodule "themes/docsy"] | ||
path = themes/docsy | ||
url = https://github.com/google/docsy.git |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,26 @@ | ||
#!/bin/sh | ||
|
||
# Setup git info to actually do a commit | ||
git config --global user.email "54143644+lingua-pupuli-bot@users.noreply.github.com" | ||
git config --global user.name "Lingua Pupuli Bot" | ||
|
||
# If a command fails then the deploy stops | ||
set -e | ||
|
||
# ------ VSCode Website | ||
# Go To Public folder | ||
pushd public/vscode | ||
|
||
# Add changes to git. | ||
git add . | ||
|
||
# Commit changes. | ||
msg="rebuilding site $(date)" | ||
if [ -n "$*" ]; then | ||
msg="$*" | ||
fi | ||
git commit -m "$msg" | ||
|
||
# Push source and build repos. | ||
git push -q https://lingua-pupuli-bot:${GITHUB_TOKEN}@github.com/puppet-vscode/puppet-vscode.github.io.git master | ||
popd |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,13 @@ | ||
#!/bin/sh | ||
|
||
# Enable globs for rm | ||
shopt -s extglob; | ||
|
||
# Prep the output repositories | ||
rm -rf public/ | ||
git clone https://github.com/puppet-vscode/puppet-vscode.github.io.git public/vscode --depth 1 | ||
|
||
# Prune the old content... | ||
pushd public/vscode | ||
rm -rf !(.git) | ||
popd |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,51 @@ | ||
--- | ||
dist: xenial | ||
language: node_js | ||
node_js: 11.0.0 | ||
|
||
sudo: false | ||
|
||
# Enable for PowerShell support | ||
# addons: | ||
# apt: | ||
# sources: | ||
# - sourceline: "deb [arch=amd64] https://packages.microsoft.com/ubuntu/16.04/prod xenial main" | ||
# key_url: "https://packages.microsoft.com/keys/microsoft.asc" | ||
# packages: | ||
# - powershell | ||
|
||
git: | ||
# We do this ourselves later | ||
submodules: false | ||
|
||
branches: | ||
only: | ||
- docsy-ification # Switch to master once done. | ||
|
||
install: | ||
- wget -O /tmp/hugo.deb https://github.com/gohugoio/hugo/releases/download/v0.57.0/hugo_extended_0.57.0_Linux-64bit.deb | ||
- sudo dpkg -i /tmp/hugo.deb | ||
- npm install | ||
|
||
# env: | ||
# global: | ||
# - GITHUB_TOKEN=supersecret | ||
|
||
script: | ||
- hugo version; | ||
pushd themes/docsy; | ||
git submodule update -f --init --recursive --depth 1; | ||
popd; | ||
export HUGO_ENV=production; | ||
- bash .travis-ci/pre-deploy.sh | ||
- hugo --source vscode --destination '../public/vscode'; | ||
hugo --source editor-services --destination '../lingua-pupuli/static/editor-services'; | ||
hugo --source editor-syntax --destination '../lingua-pupuli/static/editor-syntax'; | ||
hugo --source lingua-pupuli --destination '../public/lingua-pupuli' | ||
|
||
deploy: | ||
- provider: script | ||
script: bash .travis-ci/deploy.sh | ||
skip_cleanup: true | ||
on: | ||
branch: docsy-ification # Switch to master once done. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,86 @@ | ||
# docs | ||
Puppet VSCode Extension and Language Server Documentation Website | ||
|
||
## Cloning | ||
|
||
This project uses git submodules | ||
|
||
``` | ||
git clone --recurse-submodules https://github.com/lingua-pupuli/docs.git | ||
``` | ||
|
||
To update the Docsy theme use | ||
|
||
``` | ||
git submodule update --init --recursive --depth 1 | ||
``` | ||
|
||
## Lingua-Pupuli Umbrella Project | ||
|
||
This hugo site needs the editor-services and editor-syntax site built first, into the `lingua-pupuli/static/<...>` directory | ||
|
||
``` | ||
> hugo --source editor-services --destination '../lingua-pupuli/static/editor-services' | ||
> hugo --source editor-syntax --destination '../lingua-pupuli/static/editor-syntax' | ||
> hugo server --bind "0.0.0.0" --source lingua-pupuli | ||
``` | ||
|
||
## VSCode | ||
|
||
``` | ||
hugo server --bind "0.0.0.0" --source vscode | ||
``` | ||
|
||
## Updating the websites from source code | ||
|
||
Parts of the websites are automatically generated from source code (e.g. the VS Code `package.json` file). A PowerShell script has been created to automatically parse the source code, and update the relevant websites. | ||
|
||
Steps: | ||
|
||
1. Clone the source repositories and checkout their required branch/tag/reference. Note the directories where they were cloned to as it is required for step 2. | ||
|
||
- Puppet VS Code Extension : https://github.com/lingua-pupuli/puppet-vscode.git | ||
|
||
2. Run the `update-from-source.ps1` PowerShell script. | ||
|
||
``` powershell | ||
> .\update-from-source.ps1 -ExtensionSourcePath '<Path to Puppet VS Code Extension>' | ||
``` | ||
|
||
3. Commit the changes and create a Pull Request to merge them into the docs repository. | ||
|
||
## Guidelines | ||
|
||
### Creating animated GIFS | ||
|
||
- Size should be 1200px wide and 750px high (Or percentage thereof) | ||
|
||
Use the `tools\SetVSCodeWindow.ps1` script to help automatically set the size | ||
|
||
- VS Code should be zoomed to +140% | ||
|
||
VS Code setting: `"window.zoomLevel": 2` | ||
|
||
- Have blue border (Not required, but nice for consistency). This basically means use VS Code stable, not Insiders | ||
|
||
- Use the latest VS Code edition | ||
|
||
- Close explorer bar if it's not needed. If it is needed keep the number of files shown to a minimum to avoid distraction _OR_ use a real life example (e.g. puppetlabs-stdlib) | ||
|
||
- Reduce palette clutter where possible | ||
|
||
Disable extensions like Docker, Live Share etc. that add toolbar and status bar icons | ||
|
||
- Probably best to use default font (not ligatures) | ||
|
||
- Speed up frames to avoid users staring at a blank gif | ||
|
||
- 10fps is probably a good frame rate to record at | ||
|
||
- Set it to looping | ||
|
||
- A good starting point is decrease the timing of all frames by 40ms | ||
|
||
- Set the last frame to 1000ms |
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
baseURL = "http://example.org/" | ||
languageCode = "en-us" | ||
title = "Puppet Editor Services" | ||
|
||
# Hugo allows theme composition (and inheritance). The precedence is from left to right. | ||
themesDir = "../themes" | ||
theme = ["docsy"] | ||
|
||
disableKinds = ["taxonomy", "taxonomyTerm"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
+++ | ||
title = "Home" | ||
linkTitle = "Home" | ||
+++ | ||
|
||
{{ define "main" }} | ||
|
||
{{< blocks/section >}} | ||
<h1>Coming soon...</h1> | ||
|
||
{{% /blocks/section %}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
{{ define "main"}} | ||
<main id="main"> | ||
<div> | ||
<h1 id="title">Not found</h1> | ||
<p>Oops! This page doesn't exist. Try going back to our <a href="{{ "/" | relURL }}">home page</a>.</p> | ||
|
||
<p>You can learn how to make a 404 page like this in <a href="https://gohugo.io/templates/404/">Custom 404 Pages</a>.</p> | ||
</div> | ||
</main> | ||
{{ end }} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
baseURL = "http://example.org/" | ||
languageCode = "en-us" | ||
title = "Puppet Editor Syntax" | ||
|
||
# Hugo allows theme composition (and inheritance). The precedence is from left to right. | ||
themesDir = "../themes" | ||
theme = ["docsy"] | ||
|
||
disableKinds = ["taxonomy", "taxonomyTerm"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
+++ | ||
title = "Home" | ||
linkTitle = "Home" | ||
+++ | ||
|
||
{{ define "main" }} | ||
|
||
{{< blocks/section >}} | ||
<h1>Coming soon...</h1> | ||
|
||
{{% /blocks/section %}} |
Oops, something went wrong.