rundoc 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ed87bdf4593dcd65e6823a9ef5231802b0282aed932c119022cfc44d2ec6f9d8
-  data.tar.gz: 0d7a80aab3b225049978eb30ca301f817203a564aa9787dcd0026a89b61c101d
+  metadata.gz: e99ebdb76543d50700d87e4e1d369584785d88500a4ba261b203fc526391234a
+  data.tar.gz: 41c77800630c17ca1cb1e123cd9930290bcdd3e6bf87c7db42da3e4d32159070
 SHA512:
-  metadata.gz: ff4a68baac0e70330af729e752dc96e01c95e1da4ffe0e4850d8fca619e026adbaea940fed31982d41bcc41308ffdb7c3625145c2209ea0db7ec22b714738377
-  data.tar.gz: '09e9a757c31ea81c31b1e1d1c70da5241f2b756c39a2f6701e0d4b9f2a108647d21fb6d40edd31417b5136f3eb72f802c03020b7af9d42677d8f6efd96e3bf4d'
+  metadata.gz: f7e5ab57b964760255e72017c7caa23b13ed3b4042763858d56518a737cf9ac0274f0c8a9c1189b0af061ff47f250cf9438e38302a5664b469166071ff380bf2
+  data.tar.gz: f086f8a367a1770d6dd9bb85832637e94d93b8198e2eaf5e2c38f4b20881a852134d148a9655c517e1eb41c81f1797003e16cd0b1137ddba88ac2c494ca38649

data/.gitignore

@@ -1,7 +1,14 @@
 test/fixtures/*/project/
 test/fixtures/*/tmp/
 test/fixtures/*/myapp/
+
+test/fixtures/*/*/project/
+test/fixtures/*/*/tmp/
+test/fixtures/*/*/myapp/
+
+
 *.gem
 
 .DS_Store
 Gemfile.lock
+.env

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+## master
+
+## 1.0.1
+
+- Allow non-headless browser sessions and navigation [#23](https://github.com/schneems/rundoc/pull/23)
+- Fix issue where a background task's log file was not present before it was attempted to be opened.
+- Allow composability of documents `rundoc.depend_on` and `rundoc.require` [#19](https://github.com/schneems/rundoc/pull/19)
+- The `rundoc` command is now `rundoc.configure`.
+- Ignore chdir warning since that affect is intentional [#20](https://github.com/schneems/rundoc/pull/20)
+
 ## 1.0.0
 
 - Now using a propper PEG parser (parslet)

data/README.md

@@ -4,34 +4,29 @@
 
 ## What
 
-This library allows you to "run" your docs and embed the code as well as results back into the documentation.
+This library allows you to "run" your docs and embed the code as well as results back into the documentation. Here's a quick example:
 
-Write in a runDOC compatible markdown format, then run your docs to generate matching projects. Instead of writing a tutorial and then building an example separately, your documentation can build the example app for you. Not only does this keep your doc writing DRY, it also enforces consistency and accuracy. If you make a typo in your docs your project won't build...you'll get early warning and be able to fix it before it has the opportunity to confuse your reader.
+Write documentation:
 
-Think of runDOC as your ever-vigilant tech editor and writing partner.
+    Install by running:
 
-Once docs are run, they output a project and fully valid markdown doc (without any of the special runDOC tags). You could configure your project to be automatically pushed to github or anything else you want afterwards, check out the config section.
-
-Write more technical content, faster and with a better consistency by using runDOC.
-
-## Why
-
-I wrote a [Rails course for the University of Texas](http://schneems.com), that required I build an app and write
-documentation at the same time. I enjoyed the experience but having to do both essentially doubled my work load, worse than the time wasted copying snippets between the two was my docs were prone to paste errors, keyboard slips, or me just forgetting to add sections that I had implemented in the app. The only way for me to find these errors was to give the docs to someone to actually follow them and build the project. This method of manually checking is extremely time consuming, prone to errors (the developer may work around problems instead of reporting them to you), and makes making minor edits a major pain. Instead of writing your docs once and iterating, I found adding sections required me to start from scratch.
-
-
-While I was writing the course I dreamed of a system where the docs and the
-code could automatically stay in sync. One where if I had a typo in my tutorials, an automatic tech-editor would know and tell me. One where I couldn't accidentally skip over critical sections leaving true novices confused.
+    ```
+    :::>> $ gem install rails --no-document
+    ```
 
-Dream no more, because runDOC does just that:
+Now if you "run" this document you'll get this output:
 
-Write docs, build software.
+    Install by running:
 
-## Isn't this Overkill?
+    ```
+    $ gem install rails --no-document
+    Successfully installed rails-5.2.2
+    1 gem installed
+    ```
 
-No. Many new doc writers skip steps accidentally, or omit lines of code with `...` and assume their readers can follow along. Even if this is true for 80% of your users, 20% of people will become frustrated and may give up as a result. I found by including [check steps](http://schneems.com/post/60359275700/prepare-do-test-make-your-technical-writing-shine) such as running `ls` to ensure directory contents were the difference between good docs and great ones. The only problem: the output of `ls` on a Rails 4.0.0 and 4.0.1 project may be different. So the only way to ensure output is to actually run the command and copy it into your docs. With runDOC you don't need to do that. Rundoc runs the command then it can insert the output for you.
+The idea is that as your documentation "runs" it builds a working tutorial. It also acts as tests since if your docs become incorrect due to a typo or bit-rot then when you try to generate them, the process will fail.
 
-If you don't intend on updating or revising your content, then this project is overkill. On the other hand if you're writing docs without the intent of revising them, you probably shouldn't be writing technical docs.
+Think of RunDOC as your ever-vigilant tech editor and writing partner.
 
 ## Install
 
@@ -52,32 +47,53 @@ gem 'rundoc`
 Run the `rundoc build` command on any markdown file
 
 ```sh
-$ rundoc build --path runDOC.md
+$ rundoc build --path my/path/to/run_doc.md
 ```
 
-Note: This command will create and manipulate directories in the working directory of your source markdown file. Best practice is to have your source markdown file in its own empty directory.
+> Note: This command will create and manipulate directories in the working directory of your source markdown file. Best practice is to have your source markdown file in its own empty directory.
 
 This will generate a project folder with your project in it, and a markdown README.md with the parsed output of the markdown docs, and a copy of the source.
 
 ## Quick docs
 
-- [$]()
-- [fail.$]()
-- [file.write]()
-- [file.append]()
-- [file.remove]()
-- [background.start]()
-- [background.stop]()
-- [background.log.read]()
-- [background.log.clear]()
-
-## Write it:
-
-Rundoc uses github flavored markdown. This means you write like normal but in your code sections
-you can add special annotations that when run through runDOC can
+- [Understanding the Syntax](#rundoc-syntax)
+- [Dotenv support](#dotenv-support)
+- [Rendering cheat sheet](#rendering-cheat-sheet)
+
+### Commands
+
+- Execute Bash Commands
+  - [$](#shell-commands)
+  - [fail.$](#shell-commands)
+- Chain commands
+  - [pipe](#pipe)
+  - [|](#pipe)
+- Manipulate Files
+  - [file.write](#file-commands)
+  - [file.append](#file-commands)
+  - [file.remove](#file-commands)
+- Boot background processes such as a local server
+  - [background.start](#background)
+  - [background.stop](#background)
+  - [background.log.read](#background)
+  - [background.log.clear](#background)
+- Take screenshots
+  - [website.visit](#screenshots)
+  - [website.nav](#screenshots)
+  - [website.screenshot](#screenshots)
+- Configure RunDOC
+  - [rundoc.configure](#configure)
+- Import and compose documents
+  - [rundoc.depend_on](#compose-multiple-rundoc-documents)
+  - [rundoc.require](#compose-multiple-rundoc-documents)
+
+## RunDOC Syntax
+
+RunDOC uses GitHub flavored markdown. This means you write like normal but in your code sections
+you can add special annotations that when run through RunDOC can
 generate a project.
 
-All runDOC commands are prefixed with three colons `:::` and are inclosed in a code block a
+All RunDOC commands are prefixed with three colons `:::` and are inclosed in a code block a
 command such as `$` which is an alias for `bash` commands like this:
 
     ```
@@ -112,26 +128,9 @@ This code block might generate an output something like this to your markdown do
         Gemfile.lock  Rakefile  config    db    lib   public    test    vendor
     ```
 
-That's the syntax, let's look at different runDOC commands
-
-## Rendering Cheat Sheet
-
-An arrow `>` is shorthand for "render this" and a dash `-` is shorthand for skip this section. The posions two positions are command first and result second. You can skip a trailing `-`.
+### Stdin
 
-
-- `:::>-` (yes command, not result)
-- `:::>>` (yes command, yes result)
-- `:::--` (not command, not result)
-- `:::->` (not command, yes result)
-
-## Shell Commands
-
-Current Commands:
-
-- `$`
-- `fail.$`
-
-Anything you pass to `$` will be run in a shell. Any items below the command will be passed into the stdin of the bash command so:
+Any items below the command will be passed into the stdin of the command. For example using a `$` command you can effectively pipe contents to stdin:
 
     ```
     :::>> $ tail -n 2
@@ -151,7 +150,76 @@ Would output:
 
 This STDIN feature could be useful if you are running an interactive command such as `play new` which requires user input. For more fine grained input you'll need to use a custom repl object (will be covered later).
 
-If a shell command returns a non-zero exit status an error will be raised, if you expect a command to fail you can run it with `fail.$` keyword
+Different commands will do different things with this input. For example the `rundoc` command executes Ruby configuration code:
+
+    ```
+    :::-- rundoc
+    Rundoc.configure do |config|
+      config.after_build do
+        puts "you could push to GitHub here"
+        puts "You could do anything here"
+        puts "This code will run after the docs are done building"
+      end
+    end
+    ```
+
+
+And the `website.visit` command allows you to navigate and manipulate a webpage via a Capybara API:
+
+    ```
+    :::>> website.visit(name: "localhost", url: "http://localhost:3000", scroll: 100)
+    session.execute_script "window.scrollBy(0,100)"
+    session.click("sign up")
+    ```
+
+### Exact output
+
+RunDOC only cares about things that come after a `:::` section. If you have a "regular" code section, it will be rendered as as normal:
+
+    ```
+    $ echo "I won't run since i'm missing the :::>> at the front"
+    ```
+
+You can mix non-command code and commands, as long as the things that aren't rendering come first. This can be used to "fake" a command, for example:
+
+```
+$ rails new myapp # Not a command since it's missing the ":::>>""
+:::-> $ rails new myapp --skip-test --skip-yarn --skip-sprockets
+:::>> | $ head -n 5
+```
+
+This will render as:
+
+```
+$ rails new myapp # Not a command since it's missing the ":::>>""
+      create
+      create  README.md
+      create  Rakefile
+      create  .ruby-version
+      create  config.ru
+```
+
+It looks like the command was run without any flags, but in reality `rails new myapp --skip-test --skip-yarn --skip-sprockets | head -n 5` was executed.
+
+## Rendering Cheat Sheet
+
+An arrow `>` is shorthand for "render this" and a dash `-` is shorthand for skip this section. The posions two positions are **command** first and **result** second.
+
+
+- `:::>-` (yes command, not result)
+- `:::>>` (yes command, yes result)
+- `:::--` (not command, not result)
+- `:::->` (not command, yes result)
+
+## Shell Commands
+
+Current Commands:
+
+- `$`
+- `fail.$`
+
+Anything you pass to `$` will be run in a shell. If a shell command returns a non-zero exit status an error will be raised. If you expect a non-zero exit status use `fail.$` instead:
+
 
     ```
     :::>> fail.$ cat /dev/null/foo
@@ -176,7 +244,8 @@ Some commands may be custom, for example when running `cd` you likely want to ch
 However this command would fall on its face:
 
     ```
-    :::>> $ cd myapp/config && cat database.yml
+    :::>> $ cd myapp && cat config/database.yml
+    :::>> $ rails g scaffold users # <=== This command would be in the wrong directory, not `myapp`
     ```
 
 These custom commands are kept to a minimum, and for the most part behave as you would expect them to. Write your docs as you normally would and check the output frequently.
@@ -191,9 +260,7 @@ Current Commands:
 - `file.append`
 - `file.remove`
 
-If the exact filename is not known you can use a [file glob (\*)](https://github.com/schneems/rundoc/pull/6).
-
-Use the `file.write` keyword followed by a filename, on the next line(s) put the contents of the file
+Use the `file.write` keyword followed by a filename, on the next line(s) put the contents of the file:
 
     ```
     :::>- file.write config/routes.rb
@@ -207,6 +274,8 @@ Use the `file.write` keyword followed by a filename, on the next line(s) put the
     end
     ```
 
+> If the exact filename is not known you can use a [file glob (\*)](https://GitHub.com/schneems/rundoc/pull/6).
+
 If you wanted to change `users` to `products` you could write to the same file again.
 
     ```
@@ -294,7 +363,6 @@ You can stop the process by referencing the name:
 
 You can also get the log contents:
 
-
 ```
 :::>> background.log.read(name: "server")
 ```
@@ -305,12 +373,92 @@ You can also truncate the logs:
 :::>> background.log.clear(name: "server")
 ```
 
+## Screenshots
+
+You'll need selenium and `chromedriver` installed on your system to make screenshots work. On a mac you can run:
+
+```
+$ brew cask install chromedriver
+```
+
+To take a screenshot first "visit" a website. The values you pass in to stdin can be used to further navigate. For more information see the [Capybara DSL](https://www.rubydoc.info/GitHub/teamcapybara/capybara/master#the-dsl). Use the keyword `session`
+
+Once you're on the page you want to capture you can execute `website.screenshot`:
+
+```
+:::>> website.visit(name: "localhost", url: "http://localhost:3000", scroll: 100)
+session.execute_script "window.scrollBy(0,100)"
+session.first(:link, "sign up").click
+
+:::>> website.screenshot(name: "localhost")
+```
+
+The result of the screenshot command will be to replace the code section with a markdown link to a relative path of the screenshot.
+
+Once you've visited a website you can further navigate using `website.nav` or `website.navigate`:
+
+
+```
+:::>> website.visit(name: "localhost", url: "http://localhost:3000")
+:::>> website.navigate(name: "localhost")
+session.execute_script "window.scrollBy(0,100)"
+session.first(:link, "sign up").click
+
+:::>> website.screenshot(name: "localhost")
+```
+
+## Upload Screenshots
+
+You can specify that you want to upload files to S3 instead of hosting them locally by passing in `upload: "s3"` to the screenshot command:
+
+```
+:::>> website.visit(name: "localhost", url: "http://localhost:3000", scroll: 100)
+:::>> website.screenshot(name: "localhost", upload: "s3")
+```
+
+To authorize, you'll need to set these environment variables:
+
+```
+AWS_ACCESS_KEY_ID
+AWS_REGION
+AWS_SECRET_ACCESS_KEY
+AWS_BUCKET_NAME
+```
+
+The bucketeer addon on Heroku is supported out of the box. To specify project specific environment variables see the "dotenv" section below.
+
+## Compose multiple RunDOC documents
+
+If you're writing multiple tutorials that all are used together to build one larger project then you can declare dependencies inside of your RunDOC document.
+
+For example on day two (`day_two/rundoc.md`) of the tutorials you could:
+
+```
+:::-- rundoc.depend_on "../day_one/rundoc.md"
+```
+
+Now when you build `day_two/rundoc.md` it will also run the steps in `day_one/rundoc.md` first. This way you don't have to copy and paste previous commands.
+
+You can also break up your document into smaller components:
+
+
+```
+:::>> rundoc.require "../shared/rails_new.md"
+```
+
+This will replace the code section with the generated contents of `rundoc.require`.
+
+
+## Dotenv support
+
+If you need to specify project specific environment variables create a file called `.env` at the same directory as your `rundoc.md` and it will be imported. Add this file to your `.gitignore` so you don't accidentally share with the world
+
 ## Configure
 
-You can configure your docs in your docs use the `runDOC` command
+You can configure your docs in your docs use the `RunDOC` command
 
     ```
-    :::-- rundoc
+    :::-- rundoc.configure
     ```
 
 Note: Make sure you run this as a hidden command (with `-`).
@@ -321,10 +469,10 @@ This will eval any code you put under that line (in Ruby). If you want to run so
 
 
     ```
-    :::-- rundoc
+    :::-- rundoc.configure
     Rundoc.configure do |config|
       config.after_build do
-        puts "you could push to github here"
+        puts "you could push to GitHub here"
         puts "You could do anything here"
         puts "This code will run after the docs are done building"
       end
@@ -334,10 +482,10 @@ This will eval any code you put under that line (in Ruby). If you want to run so
 
 **Project Root**
 
-By default your app builds in a `tmp` directory. If any failures occur the results will remain in `tmp`. On a successful build the contents are copied over to `project`. If you are generating a new rails project in your code `$ rails new myapp`. Then the finished directory would be in `project/myapp`. If you don't like the `./project` prefix you could tell runDOC to output contents in `./myapp` instead.
+By default your app builds in a `tmp` directory. If any failures occur the results will remain in `tmp`. On a successful build the contents are copied over to `project`. If you are generating a new rails project in your code `$ rails new myapp`. Then the finished directory would be in `project/myapp`. If you don't like the `./project` prefix you could tell RunDOC to output contents in `./myapp` instead.
 
     ```
-    :::-- rundoc
+    :::-- rundoc.configure
     Rundoc.configure do |config|
       config.project_root = "myapp"
     end
@@ -350,7 +498,7 @@ This will also be the root directory that the `after_build` is executed in.
 Sometimes sensitive info like usernames, email addresses, or passwords may be introduced to the output readme. Let's say that your email address was `schneems@example.com` you could filter this out of your final document and replace it with `developer@example.com` instead like this:
 
     ```
-    :::-- rundoc
+    :::-- rundoc.configure
     Rundoc.configure do |config|
       config.filter_sensitive("schneems@exmaple.com" => "developer@example.com")
     end
@@ -358,31 +506,6 @@ Sometimes sensitive info like usernames, email addresses, or passwords may be in
 
 This command `filter_sensitive` can be called multiple times with different values. Since the config is in Ruby you could iterate over an array of sensitive data
 
-## TODO
-
-This is a section for brainstorming. If it's here it's not guaranteed to get worked on, but it will be considered.
-
-- Seperate parsing from running. This will help for easier linting of syntax etc.
-- Cache SHAs and output of each code block. If one sha changes, re-generate all code blocks, otherwise allow a re-render without code execution. Configure a check sum for busting the cache for instance a new version of Rails is released.
-
-
-- A way to run background processes indefinitely such as `rails server`
-  - Maybe a way to truncate them after only a period of time such as grab a few lines of `heroku local`.
-
-
-    ```
-    :::>- background.start(command: "rails server")
-    ```
-
-    ```
-    :::>> background.read("rails server")
-    :::>- | $ head -n 23
-    :::>- background.clear
-    ```
-
+## Copyright
 
-  - Breakpoints?
-- Better line matching for backtrace
-- `-=` command (runs command, only shows output, does not show command) ?
-- An easy test syntax?
-- Screenshot tool(s) ?!?!?!?!?!?! :)
+All content Copyright Richard Schneeman © 2019