Merge pull request #308 from getsentry/docs/improve-dev-docs

Improve the dev docs

Author: cameronmcefee

README.md

@@ -46,9 +46,11 @@ Documentation is written in Markdown, which is parsed by [kramdown](https://kram
 
 [<kbd>Read the quick reference</kbd>](https://kramdown.gettalong.org/quickref.html)
 
-## Layout components
+While the server is running, you can also view the [Markdown styleguide](http://0.0.0.0:9000/markdown-styleguide/links/)
 
-While in dev mode, the sidebar includes documentation for the special components available for formatting content.
+## Custom components
+
+While in dev mode, the sidebar includes documentation for the special tags and includes available for formatting content.
 
 ## Adding content
 

_config.yml

@@ -3,8 +3,8 @@ description: >-
   Learn how to use Sentry, configure Sentry clients, and contribute to the open
   source project on GitHub
 meta_image: default.png
-baseurl: ""
-url: "https://docs.sentry.io"
+baseurl: ''
+url: 'https://docs.sentry.io'
 twitter_username: getsentry
 home_url: https://sentry.io
 
@@ -31,12 +31,12 @@ collections:
 
 defaults:
   - scope:
-      path: ""
+      path: ''
       type: pages
     values:
       layout: doc
   - scope:
-      path: ""
+      path: ''
       type: documentation
     values:
       layout: doc
@@ -47,11 +47,15 @@ defaults:
   # object does not get clobbered so we use that to only load the dev
   # in dev mode, and these defaults here are not used in production.
   - scope:
-      path: ""
+      path: ''
       type: dev_components
     values:
-      layout: doc
+      layout: dev/default
       permalink: /:path/
+  - scope:
+      path: collections/_dev_components/markdown-styleguide/*
+    values:
+      layout: doc
 
 assets:
   source_maps: false # Prefer webpack sourcemaps
@@ -70,9 +74,8 @@ assets:
     - '*.ico'
     - 'meta/*'
 
-
 extlinks:
-  attributes: {rel: nofollow}
+  attributes: { rel: nofollow }
   rel_exclude: ['sentry.io', 'getsentry.com']
 
 # Hack to give us an empty array prototype

bin/server

@@ -41,4 +41,4 @@ rm -rf .jekyll-cache
 yarn
 (bundle check || bundle install)
 
-./bin/webpack-watch & ./bin/jekyll-watch
+./bin/webpack-watch & ./bin/jekyll-watch 

src/_data/dev_components_categories.yml

@@ -4,6 +4,10 @@
   icon: about-the-dsn
   slug: markdown-styleguide
 
-- title: Layout Components
+- title: Includes
   icon: workflow
-  slug: layout-components
+  slug: includes
+
+- title: Tags
+  icon: workflow
+  slug: tags

src/_includes/breadcrumbs.html

@@ -1,5 +1,6 @@
 {%- assign __path = page.url
   | replace: "collections/_documentation/", ""
+  | replace: "collections/_dev_components/", ""
   | split: '/'
   | pop
 -%}
@@ -16,7 +17,11 @@
     {%- if __page -%}
       <li class="breadcrumb-item"><a href="{{ __page.url }}">{{ __page.breadcrumb | default: __page.title }}</a></li>
     {%- else -%}
-      {%- assign __cateogry = site.data.documentation_categories
+      {%- assign __categories = site.data.documentation_categories -%}
+      {% if jekyll.environment == "development" %}
+      {%- assign __categories = __categories | concat: site.data.dev_components_categories -%}
+      {%- endif -%}
+      {%- assign __cateogry = __categories
         | where: 'slug', __segment
         | first
       -%}

src/_js/lib/DynamicLoad.js

@@ -95,6 +95,7 @@ class DynamicLoader {
     $('body').addClass('loading');
     loader({ pathname, hash, search })
       .then(html => {
+        $(document).trigger('page.willUpdate');
         $('body').removeClass('loading');
         if (html) replaceContent(html);
         done();

src/_js/lib/Sidebar.js

@@ -1,31 +1,35 @@
-const onlyCategories = (i, el) => {
-  const $parents = $(el).parentsUntil(
-    '[data-sidebar-root]',
-    '[data-sidebar-tree]'
-  );
-  return $parents.length === 1;
+const filterDepth = depth => {
+  return (i, el) => {
+    const $parents = $(el).parentsUntil(
+      '[data-sidebar-root]',
+      '[data-sidebar-tree]'
+    );
+    return $parents.length === depth;
+  };
 };
 
 $(document).on('page.didUpdate', function(event) {
   const $links = $('[data-sidebar-link]');
   let $active = $links.filter(`[href="${location.pathname}"]`);
+  const $categoryTree = $('[data-sidebar-tree]').filter(filterDepth(1));
   $active = !!$active.length
     ? $active
-    : $('[data-sidebar-tree]')
-        .filter(onlyCategories)
-        .eq(0)
-        .siblings('[data-sidebar-link]');
+    : $categoryTree.first().siblings('[data-sidebar-link]');
 
   $links.each((i, el) => {
     const $el = $(el);
     $el.toggleClass('active', $el.is($active));
   });
 
+  const $sectionTree = $('[data-sidebar-tree]').filter(filterDepth(0));
+
   const $trees = $('[data-sidebar-tree]');
   $trees.each((i, el) => {
     const $el = $(el);
     const containsActive = !!$el.has($active.get(0)).length;
     const isChildOfActive = $el.parent().is($active.parent());
-    $el.toggleClass('collapse', !(containsActive || isChildOfActive));
+    const isSection = $sectionTree.is($el);
+    const leaveVisble = containsActive || isChildOfActive || isSection;
+    $el.toggleClass('collapse', !leaveVisble);
   });
 });

src/_js/main.js

@@ -15,6 +15,10 @@ if (process.env.NODE_ENV === 'production') {
   Raven.config(dsn).install();
 }
 
+$(document).on('page.willUpdate', function(event) {
+  $('[data-toggle="tooltip"]').tooltip('dispose');
+});
+
 $(document).on('page.didUpdate', function(event) {
   $('[data-toggle="tooltip"]').tooltip();
 });

src/_layouts/dev/default.html

@@ -0,0 +1,43 @@
+---
+layout: doc
+---
+
+{{ page.content }}
+
+{%- if page.arguments.size > 0 -%}
+<h4>Arguments</h4>
+
+<div class="list-group">
+  {%- for arg in page.arguments -%}
+
+  <div class="list-group-item content-flush-bottom">
+    <div class="d-flex w-100 justify-content-between">
+      <h5 class="mb-1"><code>{{ arg.name }}</code></h5>
+      <small>{% if arg.required %}<strong>(Required)</strong>{% else %}(Optional){% endif %}</small>
+    </div>
+    {{ arg.desc | markdownify }}
+  </div>
+  {%- endfor -%}
+</div>
+{%- endif -%}
+
+<hr>
+
+{%- for example in page.examples -%}
+{%- if example.title -%}<h3>{{ example.title }}</h3>{%- endif -%}
+
+  {%- if example.desc -%}
+    {{ example.desc | liquify | markdownify }}
+  {%- endif -%}
+
+  <h4>Source</h4>
+
+  {%- highlight liquid -%}{{- example.source -}}{%- endhighlight -%}
+
+  <h4>Output</h4>
+
+  <div class="p-3 mb-3 mb-md-5 border rounded content-flush-bottom">
+  {{ example.output | default: example.source | liquify | markdownify }}
+  </div>
+
+{%- endfor -%}

src/collections/_dev_components/includes/alert.md

@@ -0,0 +1,43 @@
+---
+title: Alert
+arguments:
+  - name: content=""
+    type: String
+    required: true
+    desc: Content for the alert
+  - name: title=""
+    type: String
+    required: false
+    desc: Title for the alert
+  - name: level=""
+    type: String
+    required: false
+    desc: Severity of the alert. Must be a valid [Bootstrap severity level](https://getbootstrap.com/docs/4.0/components/alerts/).
+examples:
+  - title: Basic use
+    source: |
+      {% include components/alert.html
+        content="This is the body of the alert"
+      %}
+  - title: Full markdown content
+    source: |
+      {% capture markdown_content %}
+      This paragraph explains that it will be followed by a list.
+
+      - This list has three items
+      - This is the second item
+      - The last item is the best
+      {% endcapture %}
+      {% include components/alert.html
+        content=markdown_content
+      %}
+  - title: Kitchen sink
+    source: |
+      {% include components/alert.html
+        title="Pay attention"
+        content="This is the body of the alert"
+        level="danger"
+      %}
+---
+
+A box with content, with optional colors

src/collections/_dev_components/layout-components/platform-content/example_1/javascript.md renamed to src/collections/_dev_components/includes/platform-content/example-1/javascript.md

@@ -0,0 +1,32 @@
+---
+title: Platform Content
+example_string: Hello World
+arguments:
+  - name: 'content_dir="my-example"'
+    type: String
+    required: true
+    desc: Name of the folder where the examples are stored, relative to the current document
+examples:
+  - title: Basic use
+    desc: |
+      #### File Structure
+
+      ```
+      _documentation/this-category/
+        this-document.md
+        example-1/
+          javascript.md
+          python.md
+          ruby.md
+      ```
+    source: |
+      {% include components/platform_content.html content_dir="example_1" %}
+---
+
+You can customize content by platform. Within a folder in the same directory as your document, add a file for each platform you would like to include, ensuring that name of the file matches a slug in *src/data/platforms.yml*, then use the include to specify which folder to include examples from.
+
+Content is run through the Liquid compiler, then through the Markdown compiler, making it possible to create dynamic, rich styled content.
+
+The switcher will globally remember the prefered language and load it by default until changed. If no prefered language is set, the first langage provided is the default. A content platform content block does not contain the preferred language, it will display the default language for the block.
+
+You may force the platform that is displayed on the page by appending a `platform=javascript` query parameter to the page url. This will cause subsequent pages in the browsing session to display that platform. Removing the query parameter will set the page back to the default behavior of looking for the prefered platform

src/collections/_dev_components/layout-components/platform-content/example_1/python.md renamed to src/collections/_dev_components/includes/platform-content/example-1/python.md

@@ -0,0 +1,21 @@
+---
+title: User Content
+examples:
+  - title: Basic use
+    desc: |
+      {% include components/alert.html content="Do not copy and paste from this example. It contains invisible characters that prevent the tokens from rendering." %}
+    source: |
+      ```javascript
+      console.log("Your DSN is _⁣__DSN___")
+      ```
+    output: |
+      ```javascript
+      console.log("Your DSN is ___DSN___")
+      ```
+---
+
+It is possible to display a user's actual configuration information within code samples. This is done using one of the following keys:
+
+<div data-user-token-list></div>
+
+This feature only works within block level code examples, which are created using tripple tick <code>```</code> fenced code blocks in Markdown or using Jekyll's `highlight` tag.