Skip to content

Commit

Permalink
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
glennsarti committed Aug 27, 2019
1 parent 5db2748 commit ed0ddfb
Show file tree
Hide file tree
Showing 158 changed files with 5,596 additions and 440 deletions.
11 changes: 9 additions & 2 deletions .gitignore
@@ -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
3 changes: 3 additions & 0 deletions .gitmodules
@@ -0,0 +1,3 @@
[submodule "themes/docsy"]
path = themes/docsy
url = https://github.com/google/docsy.git
26 changes: 26 additions & 0 deletions .travis-ci/deploy.sh
@@ -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
13 changes: 13 additions & 0 deletions .travis-ci/pre-deploy.sh
@@ -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
51 changes: 51 additions & 0 deletions .travis.yml
@@ -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.
88 changes: 86 additions & 2 deletions README.md
@@ -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
6 changes: 0 additions & 6 deletions archetypes/default.md

This file was deleted.

21 changes: 0 additions & 21 deletions config.toml

This file was deleted.

4 changes: 0 additions & 4 deletions content/doc/installation.md

This file was deleted.

16 changes: 0 additions & 16 deletions content/feature/intellisense.md

This file was deleted.

6 changes: 0 additions & 6 deletions content/feature/linting.md

This file was deleted.

6 changes: 0 additions & 6 deletions content/feature/pdk.md

This file was deleted.

6 changes: 0 additions & 6 deletions content/feature/puppet-commands.md

This file was deleted.

5 changes: 0 additions & 5 deletions content/feature/remote-development.md

This file was deleted.

65 changes: 0 additions & 65 deletions data/features.yaml

This file was deleted.

9 changes: 9 additions & 0 deletions editor-services/config.toml
@@ -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"]
11 changes: 11 additions & 0 deletions editor-services/content/_index.html
@@ -0,0 +1,11 @@
+++
title = "Home"
linkTitle = "Home"
+++

{{ define "main" }}

{{< blocks/section >}}
<h1>Coming soon...</h1>

{{% /blocks/section %}}
10 changes: 10 additions & 0 deletions editor-services/layouts/404.html
@@ -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 }}
9 changes: 9 additions & 0 deletions editor-syntax/config.toml
@@ -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"]
11 changes: 11 additions & 0 deletions editor-syntax/content/_index.html
@@ -0,0 +1,11 @@
+++
title = "Home"
linkTitle = "Home"
+++

{{ define "main" }}

{{< blocks/section >}}
<h1>Coming soon...</h1>

{{% /blocks/section %}}

0 comments on commit ed0ddfb

Please sign in to comment.