Merge pull request primer#94 from primer/docs-publish

Doctocat documentation site, powered by YARD

Gemfile.lock

@@ -225,6 +225,7 @@ PLATFORMS
 DEPENDENCIES
   bootsnap (>= 1.4.2)
   capybara (~> 3)
+  listen (~> 3.0)
   minitest (~> 5.0)
   primer_view_components!
   pry

Procfile

@@ -1,3 +1,5 @@
 stories: cd demo; bundle install; bin/rails view_component_storybook:write_stories_json
 rails: cd demo; bundle install; STORYBOOK=true bin/rails s -p 4000
 storybook: cd demo; STORYBOOK=true bin/yarn storybook -p 5000
+build: bundle exec rake docs:livereload
+doctocat: cd docs; yarn develop

README.md

@@ -127,7 +127,7 @@ Run
 script/setup
 ```
 
-to install all necessary dependencies
+To install all necessary dependencies.
 
 ### Running tests
 
@@ -137,16 +137,20 @@ To run the full test suite:
 bundle exec rake
 ```
 
-### Storybook
+### Writing documentation
 
-*We recommend having [overmind](https://github.com/DarthSim/overmind) installed to run both rails and storybook, but it is not required.*
+Documentation is written as [YARD](https://yardoc.org/) comments directly in the source code, compiled into Markdown via `rake docs:build` and served by [Doctocat](https://github.com/primer/doctocat).
 
-To run storybook:
+### Storybook / Documentation
+
+To run Storybook and the documentation site, run:
 
 ```bash
-script/storybook
+script/dev
 ```
 
+_Note: Overmind is required to run script/dev._
+
 ### Developing with another app
 
 In your `Gemfile`, change:

Rakefile

@@ -2,13 +2,16 @@
 
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "yard"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
+YARD::Rake::YardocTask.new
+
 namespace :coverage do
   task :report do
     require "simplecov"
@@ -22,4 +25,72 @@ namespace :coverage do
   end
 end
 
+namespace :docs do
+  task :livereload do
+    require "listen"
+
+    Rake::Task["docs:build"].execute
+
+    puts "Listening for changes to documentation..."
+
+    listener = Listen.to("app") do |modified, added, removed|
+      puts "modified absolute path: #{modified}"
+      puts "added absolute path: #{added}"
+      puts "removed absolute path: #{removed}"
+
+      Rake::Task["docs:build"].execute
+    end
+    listener.start # not blocking
+    sleep
+  end
+
+  task :build do
+    require File.expand_path("../demo/config/environment.rb", __FILE__)
+    require "primer/view_components"
+
+    puts "Building YARD documentation."
+    Rake::Task["yard"].execute
+
+    puts "Converting YARD documentation to Markdown files."
+
+    registry = YARD::RegistryStore.new
+    registry.load!(".yardoc")
+    component = Primer::CounterComponent
+    documentation = registry.get(component.name)
+
+    File.open("docs/content/components/#{component.name.demodulize.gsub("Component", "").downcase}.md", "w") do |f|
+      f.puts("---")
+      f.puts("title: #{component.name}")
+      f.puts("---")
+      f.puts
+      f.puts(documentation.base_docstring)
+      f.puts
+      f.puts("## Arguments")
+      f.puts
+      f.puts("| Name | Type | Default | Description |")
+      f.puts("| :- | :- | :-: | :- |")
+
+      initialize_method = documentation.meths.find(&:constructor?)
+
+      initialize_method.tags.each do |tag|
+        if tag.tag_name == "param"
+          o = tag.object.parameters.find { |a| [tag.name.to_s, tag.name.to_s + ":"].include?(a[0]) }
+
+          default =
+            if o && o[1]
+              o[1]
+            else
+              ""
+            end
+
+
+          f.puts("| #{tag.name} | #{tag.types.join(", ")} | #{default} | #{tag.text} |")
+        end
+      end
+    end
+
+    puts "Markdown compiled."
+  end
+end
+
 task default: :test

app/components/primer/counter_component.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 module Primer
+  # Use Primer::CounterComponent to add a count to navigational elements and buttons.
   class CounterComponent < Primer::Component
     DEFAULT_SCHEME = :default
     SCHEME_MAPPINGS = {

docs/.gitignore

@@ -0,0 +1,91 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# TypeScript v1 declaration files
+typings/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variables file
+.env
+.env.test
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+
+# next.js build output
+.next
+
+# nuxt.js build output
+.nuxt
+
+# vuepress build output
+.vuepress/dist
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# Gatsby
+public/

docs/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "trailingComma": "all",
+  "bracketSpacing": false,
+  "semi": false,
+  "singleQuote": true
+}

docs/content/components/counter.md

@@ -0,0 +1,17 @@
+---
+title: Primer::CounterComponent
+---
+
+Use Primer::CounterComponent to add a count to navigational elements and buttons.
+
+## Arguments
+
+| Name | Type | Default | Description |
+| :- | :- | :-: | :- |
+| count | Integer, Float::INFINITY, nil | 0 | The number to be displayed (e.x. # of issues, pull requests) |
+| scheme | Symbol | DEFAULT_SCHEME | Color scheme. One of `SCHEME_MAPPINGS.keys`. |
+| limit | Integer | 5_000 | Maximum value to display. (e.x. if count == 6,000 and limit == 5000, counter will display "5,000+") |
+| hide_if_zero | Boolean | false | If true, a `hidden` attribute is added to the counter if `count` is zero. |
+| text | String | "" | Text to display instead of count. |
+| round | Boolean | false | Whether to apply rounding logic to value. |
+| kwargs | Hash |  | Style arguments to be passed to Primer::Classify |