Merge pull request #144 from justwriteclick/ag-gh-start

Adds an article on getting started with an existing docs repo

Author: annegentle

Gemfile.lock

@@ -1,43 +1,32 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.2.2)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-    addressable (2.5.2)
-      public_suffix (>= 2.0.2, < 4.0)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
     colorator (1.1.0)
-    colorize (0.8.1)
-    concurrent-ruby (1.1.4)
+    concurrent-ruby (1.1.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)
-    faraday (0.15.4)
+    faraday (1.0.0)
       multipart-post (>= 1.2, < 3)
-    ffi (1.10.0)
+    ffi (1.12.2)
     forwardable-extended (2.6.0)
-    gemoji (3.0.0)
-    html-pipeline (2.10.0)
-      activesupport (>= 2)
-      nokogiri (>= 1.4)
-    html-proofer (3.10.2)
-      activesupport (>= 4.2, < 6.0)
+    html-proofer (3.15.1)
       addressable (~> 2.3)
-      colorize (~> 0.8)
-      mercenary (~> 0.3.2)
-      nokogiri (~> 1.9)
+      mercenary (~> 0.3)
+      nokogumbo (~> 2.0)
       parallel (~> 1.3)
+      rainbow (~> 3.0)
       typhoeus (~> 1.3)
       yell (~> 2.0)
     http_parser.rb (0.6.0)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    jekyll (3.8.5)
+    jekyll (3.8.6)
       addressable (~> 2.4)
       colorator (~> 1.0)
       em-websocket (~> 0.5)
@@ -50,72 +39,62 @@ GEM
       pathutil (~> 0.9)
       rouge (>= 1.7, < 4)
       safe_yaml (~> 1.0)
-    jekyll-data (1.0.0)
-      jekyll (~> 3.3)
-    jekyll-feed (0.9.3)
-      jekyll (~> 3.3)
+    jekyll-feed (0.13.0)
+      jekyll (>= 3.7, < 5.0)
     jekyll-gist (1.5.0)
       octokit (~> 4.2)
     jekyll-paginate (1.1.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-theme-so-simple (3.1.2)
-      jekyll (~> 3.6)
-      jekyll-data (~> 1.0)
-      jekyll-feed (~> 0.9.2)
+    jekyll-seo-tag (2.6.1)
+      jekyll (>= 3.3, < 5.0)
+    jekyll-sitemap (1.4.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-theme-so-simple (3.2.0)
+      jekyll (>= 3.6, < 5.0)
+      jekyll-feed (~> 0.1)
       jekyll-gist (~> 1.4)
       jekyll-paginate (~> 1.1)
       jekyll-seo-tag (~> 2.4)
-      jekyll-sitemap (~> 1.1)
-      jemoji (~> 0.8)
-    jekyll-watch (2.1.2)
+      jekyll-sitemap (~> 1.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.1)
-    listen (3.1.5)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-      ruby_dep (~> 1.2)
+    liquid (4.0.3)
+    listen (3.2.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.3.6)
     mini_portile2 (2.4.0)
-    minitest (5.11.3)
-    multipart-post (2.0.0)
-    nokogiri (1.10.4)
+    multipart-post (2.1.1)
+    nokogiri (1.10.7)
       mini_portile2 (~> 2.4.0)
-    octokit (4.13.0)
+    nokogumbo (2.0.2)
+      nokogiri (~> 1.8, >= 1.8.4)
+    octokit (4.16.0)
+      faraday (>= 0.9)
       sawyer (~> 0.8.0, >= 0.5.3)
-    parallel (1.17.0)
+    parallel (1.19.1)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (3.0.3)
+    public_suffix (4.0.3)
+    rainbow (3.0.0)
     rb-fsevent (0.10.3)
-    rb-inotify (0.10.0)
+    rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rouge (3.3.0)
-    ruby_dep (1.5.0)
+    rouge (3.15.0)
     safe_yaml (1.0.5)
-    sass (3.7.3)
+    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.1)
-      addressable (>= 2.3.5, < 2.6)
-      faraday (~> 0.8, < 1.0)
-    thread_safe (0.3.6)
+    sawyer (0.8.2)
+      addressable (>= 2.3.5)
+      faraday (> 0.8, < 2.0)
     typhoeus (1.3.1)
       ethon (>= 0.9.0)
-    tzinfo (1.2.5)
-      thread_safe (~> 0.1)
-    yell (2.1.0)
+    yell (2.2.1)
 
 PLATFORMS
   ruby
@@ -125,4 +104,4 @@ DEPENDENCIES
   jekyll-theme-so-simple
 
 BUNDLED WITH
-   2.0.1
+   1.16.3

_layouts/learn.html

@@ -20,6 +20,9 @@ <h1>{{ page.title }}</h1>
         <img src="{{ page.image.thumbnail }}" alt="{{ page.image.caption }}">
        </div>
        {{ content }}
+
+       {% include sign-up.html %}
+
        </div>
      </div>
     {% include footer.html %}

_learn/00-github-for-docs-files.md

@@ -6,58 +6,36 @@ image:
   caption: "Python and Sphinx"
 ---
 
-Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from [ReStructured](http://docutils.sourceforge.net/rst.html) text files.
+Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version, and Python 2 is an unsupported Python version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from [ReStructured](http://docutils.sourceforge.net/rst.html) text files.
 
-In case you need both versions, this tutorial walks through both on a Mac. Refer to the [Downloads on the Python site](https://www.python.org/downloads/windows/) for Windows.
+In case you need both versions, refer to the [Downloads on the Python site](https://www.python.org/downloads/).
 
-#### Installing Python 2.7.x on Mac
+## Prerequisites
 
-1. Open a terminal and use `brew` to install Python 2.7.x.
+* MacOS or a Linux-based environment in which to install Python.
+* Homebrew installed on MacOS. Get installation instructions from https://brew.sh/.
 
-    ```
-    brew install python@2
-    ```
+## Installing Python 3.x
 
-#### Installing Python 3.x
+You want the latest version of Python 3 available.
 
-You also want the latest version of Python 3 available.
-
-1. Open a terminal and use brew to install the latest Python 3.x (currently 3.7).
+1. Open a terminal and use `brew` to install the latest Python 3.x (currently 3.7).
 
     ```
     brew install python
     ```
 
-#### Verifying Python 2 and Python 3
+### Verifying the Python installation
 
 1. Open a terminal.
-1. Verify that Python 2 is correctly installed.
-
-    ```
-    python2.7 -V
-    ```
-    Expected output for August 2018:
-    ```
-    Python 2.7.15
-    ```
 1. Verify that Python 3 is correctly installed.
 
-    ```
-    python3.7 -V
-    ```
-    Expected output for August 2018:
-    ```
-    Python 3.7.0
-    ```
-
-1. Check the version set as the default version, the version of Python that is executed when you simply enter `python`. The default version of Python remains a Python 2.7 version.
-
     ```
     python -V
     ```
-    Expected output for August 2018:
+    Expected output for February 2020:
     ```
-    Python 2.7.15
+    Python 3.7.6
     ```
 
 ## Set Up Virtual Environment
@@ -68,10 +46,10 @@ Most people use Virtual Environments because it's a recommended practice when wo
 
 **Python 3**
 
-1. First create a Python 3 virtual environment using the `venv` module included with Python 3. Notice the example uses `python3.7` to be clear which version of Python you want.
+1. First create a Python 3 virtual environment using the `venv` module included with Python 3.
 
     ```
-    python3.7 -m venv py3-sphinx
+    python -m venv py3-sphinx
     ```
 
 1. Now "activate" the environment. Look for the name of the virtual environment enclosed in parenthesis after activation.
@@ -88,11 +66,11 @@ Most people use Virtual Environments because it's a recommended practice when wo
 1. Now verify that `python` is now linked to Python 3.
 
     ```
-    (py3-sphinx) $ python3.7 -V
+    (py3-sphinx) $ python -V
     ```
 
     ```
-    (py3-sphinx) $ Python 3.7.2
+    (py3-sphinx) $ Python 3.7.6
     ```
 
 ## Install Sphinx in the Virtual Environment

_learn/01-sphinx-python-rtd.md

@@ -9,6 +9,12 @@ image:
 
 Jekyll is a Static Site Generator that typically accepts [Markdown](https://commonmark.org/help/) for authoring. [Jekyll](https://jekyllrb.com/) has its own documentation site and a [Quickstart](https://jekyllrb.com/docs/). To prepare your environment to build Jekyll sites locally, follow the instructions for either Windows or MacOS.
 
+## Prerequisites
+* Windows, MacOS, or a Linux-based environment.
+* On MacOS, you will install [Homebrew](https://brew.sh).
+* On Windows, you must install Docker.
+* On Windows, you must install [Git for Windows](https://gitforwindows.org/) which includes Git Bash.
+
 ## Set up Ruby and Jekyll on Windows with Docker
 
 On Windows, first install [Docker](https://docs.docker.com/docker-for-windows/) and [Git Bash](https://gitforwindows.org/), so that you are able to use Linux-based Docker images and commands. Then follow these steps to set up Jekyll and Ruby.

_learn/02-jekyll-ruby-gh-pages.md

@@ -11,6 +11,12 @@ To build Hugo sites locally, install Homebrew and Hugo. You do not need to insta
 
 Since Hugo is built on Go, you can use the binary for your operating system. No need to maintain a development environment. Upgrades are easy too, get a new binary and install it and you're upgraded.
 
+## Prerequisites
+* Windows, MacOS, or a Linux-based environment.
+* On MacOS, you will install [Homebrew](https://brew.sh).
+* On Windows, you must install Docker.
+* On Windows, you must install [Git for Windows](https://gitforwindows.org/) which includes Git Bash.
+
 ## Set up Hugo on Windows with Git Bash and Docker
 
 You can also set up Docker and then use this [Docker image](https://hub.docker.com/r/jguyomard/hugo-builder/), and set up alias commands for `hugo` running in Docker, but using the same `hugo` commands in Git Bash on Windows.

_learn/03-hugo-go-netlify.md

@@ -9,6 +9,13 @@ image:
 
 This section goes through the workflow for adding content, editing pages, and generally working on a docs site in a GitHub repo.
 
+## Prerequisites
+
+* A GitHub, GitLab, or other Git online account.
+* A Git repository already created online in one of those services (GitHub, GitLab, or other) and already cloned locally.
+
+These steps are shown from within a directory that contains the Git repository files.
+
 ## Add content to the site
 
 Once you have created files required by your static site generator, you can start writing. Begin with the index, or home page.

_learn/04-add-content-workflow.md

@@ -0,0 +1,27 @@
+---
+title: "Evaluating print, PDF, or epub output"
+layout: learn
+image:
+  path: /images/learn/print-pdf-epub.png
+  thumbnail: /images/learn/print-pdf-epub400x225.png
+---
+
+How difficult or straightforward is it to create a print or PDF format? You may want to investigate and test solutions beyond this article, as requirements and print tolerances can vary widely.
+
+### Jekyll options
+
+In the Jekyll Documentation Theme site, Tom Johnson suggests buying a license for Prince XML ($500) in order to create print-ready PDF files with the [Jekyll Documentation Theme](https://idratherbewriting.com/documentation-theme-jekyll/). The PDF layout and styles are set using CSS. Considering that the only gem solution, [jekyll-pdf](https://github.com/abeMedia/jekyll-pdf), makes PDF files of single pages rather than a collection, the third-party solution is probably the way to go. You could look into the [Open-Publisher](https://github.com/chrisanthropic/Open-Publisher) project, which is using Jekyll to create outputs that can be used as Pandoc inputs. [Pandoc](http://pandoc.org/) is a super handy conversion tool that can convert many formats to other formats, and has templating capabilities that can help.
+
+### Sphinx options
+
+When you use Read the Docs builds for deployment, you automatically get versioned documentation based on releases, as well as PDF output for the entire site. The PDF formatting is based on [LaTex](https://www.latex-project.org/), an open source typesetting system. It has page numbering, linking, and footnotes.
+
+You also notice you get an Epub output when you use [Read the Docs](https://readthedocs.org/). Sphinx does have advantages over other static site generators for book-like output options since the Read the Docs theme is so thorough.
+
+### Hugo options
+
+Hugo supports many [custom output formats through templates](https://gohugo.io/templates/output-formats/), but as of right now no one has written a series of templates for PDF, based on the discussions in various Issues, such as [#1360 Generate concatenated document for Kindle/PDF generation](https://github.com/gohugoio/hugo/issues/1360) and [#3530 Add alternative rendering format for LaTeX](https://github.com/gohugoio/hugo/issues/3530). You could also use Prince XML as a solution here, similar to Jekyll.
+
+## Other options?
+
+For the _Docs Like Code_ book, I have written an article about how I created print-ready PDF and Amazon-supported ebook files such as the MOBI format. Read more in [Practical Advice On Publishing A Technical Book using GitHub and GitBook](https://www.docslikecode.com/articles/practical-advice/). GitBook has since changed their overall pricing and support plan, but is certainly worth investigating.