diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..1cabae3 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +_site +.sass-cache +.jekyll-metadata +vendor/ +.bundle/ diff --git a/docs/404.html b/docs/404.html new file mode 100644 index 0000000..c472b4e --- /dev/null +++ b/docs/404.html @@ -0,0 +1,24 @@ +--- +layout: default +--- + + + +
+

404

+ +

Page not found :(

+

The requested page could not be found.

+
diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 0000000..3f49941 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,30 @@ +source "https://rubygems.org" + +# Hello! This is where you manage which Jekyll version is used to run. +# When you want to use a different version, change it below, save the +# file and run `bundle install`. Run Jekyll with `bundle exec`, like so: +# +# bundle exec jekyll serve +# +# This will help ensure the proper Jekyll version is running. +# Happy Jekylling! +#gem "jekyll", "~> 3.8.5" + +# This is the default theme for new Jekyll sites. You may change this to anything you like. +gem "minima", "~> 2.0" + +# If you want to use GitHub Pages, remove the "gem "jekyll"" above and +# uncomment the line below. To upgrade, run `bundle update github-pages`. +gem "github-pages", group: :jekyll_plugins + +# If you have any plugins, put them here! +group :jekyll_plugins do + gem "jekyll-feed", "~> 0.6" +end + +# Windows does not include zoneinfo files, so bundle the tzinfo-data gem +gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby] + +# Performance-booster for watching directories on Windows +gem "wdm", "~> 0.1.0" if Gem.win_platform? + diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 0000000..6e0170b --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,252 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (4.2.11.1) + i18n (~> 0.7) + minitest (~> 5.1) + thread_safe (~> 0.3, >= 0.3.4) + tzinfo (~> 1.1) + addressable (2.7.0) + public_suffix (>= 2.0.2, < 5.0) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.11.1) + colorator (1.1.0) + commonmarker (0.17.13) + ruby-enum (~> 0.5) + concurrent-ruby (1.1.5) + dnsruby (1.61.3) + addressable (~> 2.5) + em-websocket (0.5.1) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0.6.0) + ethon (0.12.0) + ffi (>= 1.3.0) + eventmachine (1.2.7) + execjs (2.7.0) + faraday (0.17.0) + multipart-post (>= 1.2, < 3) + ffi (1.11.1) + forwardable-extended (2.6.0) + gemoji (3.0.1) + github-pages (202) + activesupport (= 4.2.11.1) + github-pages-health-check (= 1.16.1) + jekyll (= 3.8.5) + jekyll-avatar (= 0.6.0) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.1.6) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.11.0) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.12.1) + jekyll-mentions (= 1.4.1) + jekyll-optional-front-matter (= 0.3.0) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.2.0) + jekyll-redirect-from (= 0.14.0) + jekyll-relative-links (= 0.6.0) + jekyll-remote-theme (= 0.4.0) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.5.0) + jekyll-sitemap (= 1.2.0) + jekyll-swiss (= 0.4.0) + jekyll-theme-architect (= 0.1.1) + jekyll-theme-cayman (= 0.1.1) + jekyll-theme-dinky (= 0.1.1) + jekyll-theme-hacker (= 0.1.1) + jekyll-theme-leap-day (= 0.1.1) + jekyll-theme-merlot (= 0.1.1) + jekyll-theme-midnight (= 0.1.1) + jekyll-theme-minimal (= 0.1.1) + jekyll-theme-modernist (= 0.1.1) + jekyll-theme-primer (= 0.5.3) + jekyll-theme-slate (= 0.1.1) + jekyll-theme-tactile (= 0.1.1) + jekyll-theme-time-machine (= 0.1.1) + jekyll-titles-from-headings (= 0.5.1) + jemoji (= 0.10.2) + kramdown (= 1.17.0) + liquid (= 4.0.0) + listen (= 3.1.5) + mercenary (~> 0.3) + minima (= 2.5.0) + nokogiri (>= 1.10.4, < 2.0) + rouge (= 3.11.0) + terminal-table (~> 1.4) + github-pages-health-check (1.16.1) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (~> 4.0) + public_suffix (~> 3.0) + typhoeus (~> 1.3) + html-pipeline (2.12.0) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.6.0) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.8.5) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (~> 1.14) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.6.0) + jekyll (~> 3.0) + jekyll-coffeescript (1.1.1) + coffee-script (~> 2.2) + coffee-script-source (~> 1.11.1) + jekyll-commonmark (1.3.1) + commonmarker (~> 0.14) + jekyll (>= 3.7, < 5.0) + jekyll-commonmark-ghpages (0.1.6) + commonmarker (~> 0.17.6) + jekyll-commonmark (~> 1.2) + rouge (>= 2.0, < 4.0) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.11.0) + jekyll (~> 3.3) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.12.1) + jekyll (~> 3.4) + octokit (~> 4.0, != 4.4.0) + jekyll-mentions (1.4.1) + html-pipeline (~> 2.3) + jekyll (~> 3.0) + jekyll-optional-front-matter (0.3.0) + jekyll (~> 3.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.2.0) + jekyll (~> 3.0) + jekyll-redirect-from (0.14.0) + jekyll (~> 3.3) + jekyll-relative-links (0.6.0) + jekyll (~> 3.3) + jekyll-remote-theme (0.4.0) + addressable (~> 2.0) + jekyll (~> 3.5) + rubyzip (>= 1.2.1, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.5.0) + jekyll (~> 3.3) + jekyll-sitemap (1.2.0) + jekyll (~> 3.3) + jekyll-swiss (0.4.0) + jekyll-theme-architect (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.5.3) + jekyll (~> 3.5) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.1) + jekyll (~> 3.3) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.10.2) + gemoji (~> 3.0) + html-pipeline (~> 2.2) + jekyll (~> 3.0) + kramdown (1.17.0) + liquid (4.0.0) + listen (3.1.5) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + ruby_dep (~> 1.2) + mercenary (0.3.6) + mini_portile2 (2.4.0) + minima (2.5.0) + jekyll (~> 3.5) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.13.0) + multipart-post (2.1.1) + nokogiri (1.10.5) + mini_portile2 (~> 2.4.0) + octokit (4.14.0) + sawyer (~> 0.8.0, >= 0.5.3) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (3.1.1) + rb-fsevent (0.10.3) + rb-inotify (0.10.0) + ffi (~> 1.0) + rouge (3.11.0) + ruby-enum (0.7.2) + i18n + ruby_dep (1.5.0) + rubyzip (2.0.0) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.8.2) + addressable (>= 2.3.5) + faraday (> 0.8, < 2.0) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + thread_safe (0.3.6) + typhoeus (1.3.1) + ethon (>= 0.9.0) + tzinfo (1.2.5) + thread_safe (~> 0.1) + unicode-display_width (1.6.0) + +PLATFORMS + ruby + +DEPENDENCIES + github-pages + jekyll-feed (~> 0.6) + minima (~> 2.0) + tzinfo-data + +BUNDLED WITH + 2.0.2 diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 0000000..bc512c7 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,42 @@ +# Welcome to Jekyll! +# +# This config file is meant for settings that affect your whole blog, values +# which you are expected to set up once and rarely edit after that. If you find +# yourself editing this file very often, consider using Jekyll's data files +# feature for the data you need to update frequently. +# +# For technical reasons, this file is *NOT* reloaded automatically when you use +# 'bundle exec jekyll serve'. If you change this file, please restart the server process. + +# Site settings +# These are used to personalize your new site. If you look in the HTML files, +# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on. +# You can create any custom variable you would like, and they will be accessible +# in the templates via {{ site.myvariable }}. +title: Vimspector Documentation +description: | + Reference Documentation for Vimspector: A multi-language debugging front + end for Vim + +# Build settings +markdown: kramdown +theme: minima +plugins: + - jekyll-feed + +header_pages: + - index.md + - configuration.md + - schema/index.md + +# Exclude from processing. +# The following items will not be processed, by default. Create a custom list +# to override the default setting. +# exclude: +# - Gemfile +# - Gemfile.lock +# - node_modules +# - vendor/bundle/ +# - vendor/cache/ +# - vendor/gems/ +# - vendor/ruby/ diff --git a/docs/configuration.md b/docs/configuration.md index ef1ba88..199ebe9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,16 +1,19 @@ -# Vimspector project configuration +--- +title: Configuration +--- + This document defines the supported format for project and adapter configuration for Vimspector. -# Concepts +## Concepts As Vimspector supports debugging arbitrary projects, you need to tell it a few deatils about what you want to debug, and how to go about doing that. In order to debug things, Vimspector requires a Debug Adapter which bridges between Vimspector and the actual debugger tool. Vimspector can be used with any -debug adapter that implemnents the [Debug Adapter Protocol][dap]. +debug adapter that implements the [Debug Adapter Protocol][dap]. For each debugging session, you provide a _debug configuration_ which includes things like: @@ -24,7 +27,7 @@ Along with optional additional configuration for things like: - Function breakpoints - Exception breakpoints -## Debug adapter configuration +### Debug adapter configuration The adapter to use for a particular debug session can be specified inline within the _debug configuration_, but more usually the debug adapter is defined @@ -32,12 +35,12 @@ separately and just referenced from the _debug configuration_. The adapter configuration includes things like: -* How to launch or connect to the debeg adapter +* How to launch or connect to the debug adapter * How to configure it for PID attachment * How to set up remote debugging, such as how to launch the process remotely (for example, under `gdbserver`, `ptvsd`, etc.) -## Debug profile configuration +### Debug profile configuration Projects can have many different debug profiles. For example you might have all of the following, for a given source tree: @@ -45,7 +48,7 @@ of the following, for a given source tree: * Remotely launch c++ the process, and break on `main` * Locally Python test and break exception * Remotely attach to a c++ process -* Locally launchg a bash script +* Locally launch a bash script * Attach to a JVM listening on a port Each of these represents a different use case and a different _debug @@ -57,10 +60,10 @@ configuration_. As mentioned above, a _debug configuration_ is essentially: process. The bulk of the configuration is the last of these, which comprises -adapter-specific opions, as the Debug Adapter Protocol does not specify any +adapter-specific options, as the Debug Adapter Protocol does not specify any standard for launch or attach configuration. -## Replacements and variables +### Replacements and variables Vimspector _debug configuration_ is intended to be as general as possible, and to be committed to source control so that debugging your applications becomes a @@ -69,9 +72,9 @@ if..." with "just hit F5 and step through!"). Therefore it's important to abstract certain details, like runtime and build-time paths, and to parameterise the _debug configuration_. Vimspector -provides a simple mechanism to do this with `${replacement}` style replacments. +provides a simple mechanism to do this with `${replacement}` style replacements. -The values avaiable within the `${...}` are defined below, but in summary the +The values available within the `${...}` are defined below, but in summary the following are supported: * Environment variables, such as `${PATH}` @@ -112,8 +115,8 @@ But for now, consider the following example snippet: } ``` -In this (ficticious) example the `program` launch configuration item contains -the following variable substiutions: +In this (fictitious) example the `program` launch configuration item contains +the following variable substitutions: * `${fileBasenameNoExtension}` - this is a [Predefined Variable](#predefined-variables), set by Vimspector to the base name of the @@ -121,18 +124,18 @@ the following variable substiutions: `xyz`). * `${USER}` - this refers to the Environment Variable `USER`. * `${TestIdentifier}` - this variable is not defined, so the user is asked to - provide a value interractively when starting debugging. Vimspector remembers + provide a value interactively when starting debugging. Vimspector remembers what they said and provides it as the default should they debug again. * `${SecretToken}` - this variable is provided by the configuration's `variables` block. Its value is taken from the `strip`ped result of running the shell command. Note these variables can be supplied by both the debug and adapter configurations and can be either static strings or shell commands. -# Configuration Format +## Configuration Format All Vimspector configuration is defined in a JSON object. The complete specification of this object is available in the [JSON Schema][schema], but -the basic format for the configuation object is: +the basic format for the configuration object is: ``` { @@ -144,13 +147,13 @@ the basic format for the configuation object is: The `adapters` key is actually optional, as `` can be embedded within ``, though this is not recommended usage. -# Files and locations +## Files and locations The above configuration object is constructed from a number of configuration files, by merging objects i specified order. In a minimal sense, the only file required is a `.vimspector.json` file in the -root of your project which deinfes the [full configuration object][schema], but +root of your project which defines the [full configuration object][schema], but it is usually useful to split the `adapters` configuration into a separate file (or indeed one file per debug adapter). @@ -161,10 +164,10 @@ abbreviations: `$HOME/.vim/pack/vimspector/start/vimspector`) * `` is either `macos` or `linux` depending on the host operating system. -# Adapter configurations +## Adapter configurations Vimspector reads a series of files to build the `adapters` object. The -`adapters` objects are merged in such a way that a defintion for an adapter +`adapters` objects are merged in such a way that a definition for an adapter named `example-adapter` in a later file _completely replaces_ a previous definition. @@ -198,12 +201,12 @@ Adapter configurations are re-read at the start of each debug session. The specification for the gadget object is defined in the [gadget schema][]. -# Debug configurations +## Debug configurations -The debug conifgurations are read from `.vimspector.json`. The file is found +The debug configurations are read from `.vimspector.json`. The file is found (like `.gadgets.json` above) by recursively searching up the directory hierarchy from the directory of the file open in Vim. The first file found is read and no -futher searching is done. +further searching is done. Only a single `.vimspector.json` is read. @@ -227,7 +230,7 @@ typical example looks like this: } ``` -# Predefined Variables +## Predefined Variables The following variables are provided: @@ -248,7 +251,7 @@ The following variables are provided: * `${fileExtname}` - the current opened file's extension * `${cwd}` - the current working directory of the active window on launch -# Appendix: Editor configuration +## Appendix: Editor configuration If you would like some assistance with writing the JSON files, and your editor of choice has a way to use a language server, you can use the diff --git a/docs/index.md b/docs/index.md index 3da138b..b568203 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,17 +1,23 @@ -# Vimsepctor +--- +title: Vimspector Reference Guide +--- This section contains reference material for configuring and using -[Vimsepctor][vimspector]. It is intentionally technical in nature and should +[Vimspector][vimspector]. It is intentionally technical in nature and should serve as a reference guide, rather than a user guide or tutorial. It complements the following: -* The [Vimspector README], which contains a general overview and is the main - go-to for getting started, installation, etc. -* The [Vimspector Website], which contains a step-by-step tutorial and some - detais about the user interface. +* The [Vimspector README][readme], which contains a general overview and is the + main go-to for getting started, installation, etc. +* The [Vimspector Website][website], which contains a step-by-step tutorial and + some detail about the user interface. -# Contents +## Contents -* [Configuring Vimspector](configuration.html) -* [JSON Schema](schema/) +* [Configuring Vimspector for your projects](configuration.html) +* [Full JSON Schema reference](schema/) + +[vimspector]: https://github.com/puremourning/vimspector +[readme]: https://github.com/puremourning/vimspector/blob/master/README.md +[website]: https://puremourning.github.io/vimspector-web diff --git a/docs/schema/index.md b/docs/schema/index.md index f5d00a9..2b1bb27 100644 --- a/docs/schema/index.md +++ b/docs/schema/index.md @@ -1,4 +1,6 @@ -# Vimsepctor JSON Schema +--- +title: Configuration Schema +--- This area contains the [JSON Schema][json-schema] representation of the configuration objects used for configuring Vimspector. For more information on @@ -8,7 +10,7 @@ Schema](http://json-schema.org/understanding-json-schema) Vimsepctor specification is based on [Draft 7][draft-7] of JSON Schema standard. -# The schemas +## The schemas * [`vimspector.schema.json`](vimspector.schema.json) - contains the full configuration defnition (`.vimspector.json`). diff --git a/support/site/jekyll/.gitignore b/support/site/jekyll/.gitignore new file mode 100644 index 0000000..011d9d8 --- /dev/null +++ b/support/site/jekyll/.gitignore @@ -0,0 +1,2 @@ +vendor/ +.bundle diff --git a/support/site/jekyll/Gemfile b/support/site/jekyll/Gemfile new file mode 100644 index 0000000..2c01300 --- /dev/null +++ b/support/site/jekyll/Gemfile @@ -0,0 +1,2 @@ +source 'https://rubygems.org' +gem 'jekyll', '3.8.5' diff --git a/support/site/jekyll/Gemfile.lock b/support/site/jekyll/Gemfile.lock new file mode 100644 index 0000000..2367501 --- /dev/null +++ b/support/site/jekyll/Gemfile.lock @@ -0,0 +1,61 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.7.0) + public_suffix (>= 2.0.2, < 5.0) + colorator (1.1.0) + concurrent-ruby (1.1.5) + em-websocket (0.5.1) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0.6.0) + eventmachine (1.2.7) + ffi (1.11.1) + forwardable-extended (2.6.0) + http_parser.rb (0.6.0) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.8.5) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (~> 1.14) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-watch (2.2.1) + listen (~> 3.0) + kramdown (1.17.0) + liquid (4.0.3) + listen (3.2.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.3.6) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (4.0.1) + rb-fsevent (0.10.3) + rb-inotify (0.10.0) + ffi (~> 1.0) + rouge (3.12.0) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + +PLATFORMS + ruby + +DEPENDENCIES + jekyll (= 3.8.5) + +BUNDLED WITH + 2.0.2