lingua-pupuli / docs Goto Github PK

View Code? Open in Web Editor NEW

2.0 5.0 37.0 11.01 MB

Puppet VSCode Extension and Language Server Documentation Website

License: Apache License 2.0

HTML 55.70% PowerShell 39.35% SCSS 1.93% Dockerfile 3.03%

docs's Introduction

The central Lingua-Pupuli docs site

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 50

Requirements

Hugo Extended. See Docsy Getting Started for more information.

For Windows users, chocolatey hosts a Hugo Extended package

NodeJS with PostCSS installed. This is available via npm install. See Docsy Getting Started for more information.

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

Using VSCode Dev Containers

Due to fsnotify not being able to watch Windows mounts inside docker containers, Hugo may not see file changes and will not trigger a rebuild automatically. This is a known problem with Docker/VScode/WSL2/WSL1. To workaround this issue either; do not use Windows to host Linux containers (which is 😢) or use the Clone in Volume feature.

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:

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/puppetlabs/puppet-vscode.git
Run the update-from-source.ps1 PowerShell script.

> .\update-from-source.ps1 -ExtensionSourcePath '<Path to Puppet VS Code Extension>'

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

docs's People

Contributors

Stargazers

Watchers

docs's Issues

Update links for new Puppet Docs website

Puppet has changed their docs website so most of our links are now broken :-(

Time to fix them all up.

Experiencing a Problem?

Add docs for vscode formatting.

Document Puppetfile Validator

Document feature puppetlabs/puppet-editor-services#198

Document Go to Definition Functionality

We should document the Go to Definition functionality so that a user knows what is provided in which type of workspace. Some context to start with is below.

The extension should already detect if the folder opened is part of a control repository, so you shouldn't need to add

The rules to detect are:

You must be opening a Folder (aka workspace) in VSCode, not a single file
You must be opening a Folder either at the root of, or inside of, the control repo. Not outside of it.
The control repo must contain an environment.conf
The control repo must NOT contain a metadata,json file. If you have both, the extension will assume it's inside a module (not a control repo)

Now there are some cases where using that setting is needed. For example, I know that @genebean has a folder containing all of the download modules from Onceover, and he needs to add the Onceover path to get the intellisense.

Some code references:

https://github.com/puppetlabs/puppet-editor-services/blob/master/lib/puppet-languageserver/document_store.rb#L105-L132

https://github.com/puppetlabs/puppet-editor-services/blob/master/spec/languageserver-sidecar/integration/puppet-languageserver-sidecar/puppet-languageserver-sidecar_spec.rb#L226-L249

Originally posted by @glennsarti in puppetlabs/puppet-vscode#636 (comment)

Documentation: Releases Tag not updated with latest

I'm not sure how the Releases tab on the website is updated but it looks like its missing the 0.21.0 release changelog info:

Document using installType and installDirectory

The extension works when there is both pdk and agent present, and when only one is present. The problem here is that the settings for the extension are not helping the user choose successful configurations and allowing mixing of settings that then produce incorrect paths to the parts of puppet we need.

The intention for auto was to not use installDirectory or installType, so that the extension would choose whether to use pdk or agent and which paths to use itself. This was intended to make the default 'happy path' the situation where a user has pdk installed to the default path and not require the user to set any settings.

Items to document:

If you installed either pdk or agent to the default install paths, and you want the extension to figure out whether to use pdk or agent, then do not set any settings.
If you installed either pdk or agent to the default install paths, but want to choose whether to use pdk or agent, set installType and omit installDirectory.
If you installed either pdk or agent to custom install paths, you must specify installType as either agent or pdk, and set installDirectory to the correct path.

Originally posted by @jpogran in puppetlabs/puppet-vscode#668 (comment)

Post "Use Docsy" tasks

Once PR #4 is merged there is followup work to do, to automate the deployment of the website:

Remove the Travis CI automation on my fork https://github.com/glennsarti/docs/tree/docsy-ification
Enable Travis CI on this repo
Change travis.yml and change the branch from docsy-ification to master as per commented code
Add GITHUB_TOKEN environment secret into Travis CI repo screen.

Create branch - https://github.com/lingua-pupuli/docs/tree/docsy-ification
Trim all config.toml files
Add Google Analytics from old config.toml
Add output repos as submodules
Automate build and release process