{"action":"created","comment":{"url":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/comments/69336789","id":69336789,"diff_hunk":"@@ -0,0 +1,548 @@\n+An introduction to Sphinx and Read the Docs for Technical Writers\n+=================================================================\n+\n+By: Eric Holscher\n+\n+Bio: Eric Holscher is the co-founder of Read the Docs, and the Write the Docs conference.\n+Along with community organizing and open source work,\n+he does consulting around software documentation and speaks at a number of industry events each year.\n+When he isn't expressing his views on software docs, he's getting views from the top of mountains.\n+\n+Treating documentation as code is becoming a major theme in the software industry.\n+This is coming from both sides,\n+with developers starting treat documentation as a priority alongside tests and code,\n+and writers seeing a lot of value in integrating more into the development process.\n+This marrying of cultures isn't simple,\n+but having the proper tools for the job makes both sides happy with the results that get produced.\n+\n+A lot of developer tools don't work well for writers.\n+Sphinx and Read the Docs are unique in this ecosystem,\n+in that they have powerful tools that both writers and developers want,\n+in one convenient package.\n+\n+Overview of the Ecosystem\n+-------------------------\n+\n+Read the Docs is the largest open source documentation hosting site in the world.\n+Open Source in this context means both that the code is open source,\n+and the documentation hosted is for open source software.\n+It is a developer focused platform,\n+but it has most of the features that technical writers have come to expect in a tool as well.\n+This blending of worlds makes it the best suited platform for teams that want both writers and developers contributing to product and API documentation.\n+\n+Read the Docs is best thought of as a continuous documentation platform for Sphinx.\n+Continuous documentation is analogous to continuous integration of code.\n+In practice it means that your documentation is built,\n+tested, \n+and updated on every commit.\n+\n+Sphinx provides a documentation generator that is best-in-class for software docs.\n+Sphinx documents are written in the reStructuredText markup language.\n+which is similar to Markdown,\n+but much more powerful.\n+Read the Docs provides a hosting platform for Sphinx.\n+\n+As a writer who uses Sphinx,\n+your day to day is writing reStructuredText in plain text files.\n+You then build your documentation by running Sphinx on the command line.\n+Generally it's easiest to output HTML for local writing and testing,\n+and then you can let Read the Docs generate PDF's and other formats.\n+\n+This article provides an overview of the features of Sphinx and Read the Docs,\n+and allow you to evaluate them for use in your organization.\n+\n+Introduction to Sphinx\n+----------------------\n+\n+`Sphinx <http://www.sphinx-doc.org/>`_ is the documentation tool of choice for the Python language community,\n+and increasingly also for other programming languages and tools.\n+It was `originally created <https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)>`_ in 2008 to document the Python language itself.\n+\n+Over the past eight years,\n+it has turned into a robust and mature solution for software documentation.\n+It includes a number of features that writers expect,\n+such as:\n+\n+* Single Source Publishing \n+    * Output HTML, PDF, ePub, and more\n+    * Content reuse through includes\n+    * Conditional includes based on content type and tags\n+* Multiple mature HTML themes that look beautiful on mobile and desktop\n+* Referencing across pages, documents, and projects\n+* Index and Glossary support\n+* Internationalization support\n+\n+It also has practical and powerful tools for documenting software specifically,\n+including:\n+\n+* Semantic referencing of software concepts, including classes, functions, programs, variables, etc.\n+* Including code comments in documentation output for many programming languages\n+* Tools for documenting HTTP APIs\n+* Extensions with the Python language\n+* A vast array of third party extensions to do useful things\n+\n+This article isn't large enough to cover all of the power packed into this tool.\n+But I hope to show enough to pique reader interest so that you can try these tools out and research their capacity for yourself.\n+\n+Using Sphinx\n+~~~~~~~~~~~~\n+\n+reStructuredText is a powerful language primarily because the syntax can be extended.\n+reStructuredTest supports two types of extension:\n+\n+* Paragraph level (with Directives)\n+* Inline level (with Interpreted Text Roles, or roles for short)\n+\n+Paragraph Level Markup\n+``````````````````````\n+\n+Let's see a basic example of a *Directive* in reStructuredText::\n+\n+    .. warning:: Here be dragons! This topic covers a number of options that\n+       might alter your database.\n+\n+       Proceed with caution!\n+\n+    .. figure:: screenshot-control-panel.jpg\n+       :width: 50%\n+\n+       An overview of the admin control panel.\n+\n+Here ``warning`` acts as the name of the directive,\n+and is the part you can extend for custom directives.\n+In the ``figure``,\n+``screenshot-control-panel.jpg`` is an *argument*,\n+``:width:`` is an *option*,\n+and the rest is the *content*\n+They allow for customization of directives,\n+and show the full power of reStructuredText.\n+\n+.. note:: You'll notice that Sphinx uses whitespace to denote where a directive ends.\n+   The \"Proceed with caution!\" is still part of the ``warning``,\n+   and everything that continues to be indented will be part of that warning.\n+\n+Sphinx ships with a number of powerful directives,\n+and you can also write your own if you have someone on your team that knows Python.\n+\n+Inline Markup\n+`````````````\n+\n+For extendability inside of your prose Sphinx uses roles.\n+Here is an example:\n+\n+    You can learn more about this in :rfc:`1984`.\n+    It is implemented in our code at :class:`System.Security`\n+\n+Here you can see ``rfc`` and ``class`` act as the name of the role,\n+and then you can pass in a single argument.\n+For the ``rfc`` role,\n+it generates a link to the online reference for RFC 1984 with a text of ``RFC 1984``.\n+\n+The ``class`` is where things get interesting.\n+This acts as a reference to the class ``System.Security`` that is documented in your project,\n+which is a hyperlink in the HTML output,\n+but also a working link in PDF and other outputs as well.\n+\n+Similarly,\n+you can implement your own roles with Python.\n+This allows you to create powerful semantic constructs into the actual *markup* you're using to write documentation.\n+\n+Now,\n+let's see how you take these sets of reStructuredText files and turn them into a document set.\n+\n+Table of Contents Tree\n+----------------------\n+\n+One of the main concepts in Sphinx is that it allows multiple pages to be combined into a cohesive hierarchy.\n+The ``toctree`` directive is a fundamental part of this structure.\n+\n+.. code-block:: rst\n+\n+  .. toctree::\n+     :maxdepth: 2\n+\n+     install\n+     support\n+\n+The above example outputs a Table of Contents in the page where it occurs.\n+The ``maxdepth`` argument tells Sphinx to include 2 levels of headers.\n+This also tells Sphinx that the other pages are sub-pages of the current page,\n+creating a \"tree\" structure of the pages::","path":"site/blog/2016/jul/1/sphinx-and-rtd-for-writers.rst","position":170,"original_position":170,"commit_id":"66271735b43d8a518bba9e789f599294176163a1","original_commit_id":"66271735b43d8a518bba9e789f599294176163a1","user":{"login":"ericholscher","id":25510,"avatar_url":"https://avatars.githubusercontent.com/u/25510?v=3","gravatar_id":"","url":"https://api.github.com/users/ericholscher","html_url":"https://github.com/ericholscher","followers_url":"https://api.github.com/users/ericholscher/followers","following_url":"https://api.github.com/users/ericholscher/following{/other_user}","gists_url":"https://api.github.com/users/ericholscher/gists{/gist_id}","starred_url":"https://api.github.com/users/ericholscher/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ericholscher/subscriptions","organizations_url":"https://api.github.com/users/ericholscher/orgs","repos_url":"https://api.github.com/users/ericholscher/repos","events_url":"https://api.github.com/users/ericholscher/events{/privacy}","received_events_url":"https://api.github.com/users/ericholscher/received_events","type":"User","site_admin":false},"body":"That's actually RST shorthard for \"the next section is a code example\" and will properly output one : in the output. ","created_at":"2016-07-01T18:10:56Z","updated_at":"2016-07-01T18:10:56Z","html_url":"https://github.com/ericholscher/ericholscher.com/pull/5#discussion_r69336789","pull_request_url":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/5","_links":{"self":{"href":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/comments/69336789"},"html":{"href":"https://github.com/ericholscher/ericholscher.com/pull/5#discussion_r69336789"},"pull_request":{"href":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/5"}}},"pull_request":{"url":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/5","id":76012777,"html_url":"https://github.com/ericholscher/ericholscher.com/pull/5","diff_url":"https://github.com/ericholscher/ericholscher.com/pull/5.diff","patch_url":"https://github.com/ericholscher/ericholscher.com/pull/5.patch","issue_url":"https://api.github.com/repos/ericholscher/ericholscher.com/issues/5","number":5,"state":"open","locked":false,"title":"Add sphinx & rtd draft","user":{"login":"ericholscher","id":25510,"avatar_url":"https://avatars.githubusercontent.com/u/25510?v=3","gravatar_id":"","url":"https://api.github.com/users/ericholscher","html_url":"https://github.com/ericholscher","followers_url":"https://api.github.com/users/ericholscher/followers","following_url":"https://api.github.com/users/ericholscher/following{/other_user}","gists_url":"https://api.github.com/users/ericholscher/gists{/gist_id}","starred_url":"https://api.github.com/users/ericholscher/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ericholscher/subscriptions","organizations_url":"https://api.github.com/users/ericholscher/orgs","repos_url":"https://api.github.com/users/ericholscher/repos","events_url":"https://api.github.com/users/ericholscher/events{/privacy}","received_events_url":"https://api.github.com/users/ericholscher/received_events","type":"User","site_admin":false},"body":null,"created_at":"2016-07-01T17:32:46Z","updated_at":"2016-07-01T18:10:56Z","closed_at":null,"merged_at":null,"merge_commit_sha":"fad7a1a0dfdd981ebf4f27f4faf1af0424097a49","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/5/commits","review_comments_url":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/5/comments","review_comment_url":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/comments{/number}","comments_url":"https://api.github.com/repos/ericholscher/ericholscher.com/issues/5/comments","statuses_url":"https://api.github.com/repos/ericholscher/ericholscher.com/statuses/66271735b43d8a518bba9e789f599294176163a1","head":{"label":"ericholscher:stc-article","ref":"stc-article","sha":"66271735b43d8a518bba9e789f599294176163a1","user":{"login":"ericholscher","id":25510,"avatar_url":"https://avatars.githubusercontent.com/u/25510?v=3","gravatar_id":"","url":"https://api.github.com/users/ericholscher","html_url":"https://github.com/ericholscher","followers_url":"https://api.github.com/users/ericholscher/followers","following_url":"https://api.github.com/users/ericholscher/following{/other_user}","gists_url":"https://api.github.com/users/ericholscher/gists{/gist_id}","starred_url":"https://api.github.com/users/ericholscher/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ericholscher/subscriptions","organizations_url":"https://api.github.com/users/ericholscher/orgs","repos_url":"https://api.github.com/users/ericholscher/repos","events_url":"https://api.github.com/users/ericholscher/events{/privacy}","received_events_url":"https://api.github.com/users/ericholscher/received_events","type":"User","site_admin":false},"repo":{"id":8717186,"name":"ericholscher.com","full_name":"ericholscher/ericholscher.com","owner":{"login":"ericholscher","id":25510,"avatar_url":"https://avatars.githubusercontent.com/u/25510?v=3","gravatar_id":"","url":"https://api.github.com/users/ericholscher","html_url":"https://github.com/ericholscher","followers_url":"https://api.github.com/users/ericholscher/followers","following_url":"https://api.github.com/users/ericholscher/following{/other_user}","gists_url":"https://api.github.com/users/ericholscher/gists{/gist_id}","starred_url":"https://api.github.com/users/ericholscher/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ericholscher/subscriptions","organizations_url":"https://api.github.com/users/ericholscher/orgs","repos_url":"https://api.github.com/users/ericholscher/repos","events_url":"https://api.github.com/users/ericholscher/events{/privacy}","received_events_url":"https://api.github.com/users/ericholscher/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/ericholscher/ericholscher.com","description":"Personal website.","fork":false,"url":"https://api.github.com/repos/ericholscher/ericholscher.com","forks_url":"https://api.github.com/repos/ericholscher/ericholscher.com/forks","keys_url":"https://api.github.com/repos/ericholscher/ericholscher.com/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ericholscher/ericholscher.com/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ericholscher/ericholscher.com/teams","hooks_url":"https://api.github.com/repos/ericholscher/ericholscher.com/hooks","issue_events_url":"https://api.github.com/repos/ericholscher/ericholscher.com/issues/events{/number}","events_url":"https://api.github.com/repos/ericholscher/ericholscher.com/events","assignees_url":"https://api.github.com/repos/ericholscher/ericholscher.com/assignees{/user}","branches_url":"https://api.github.com/repos/ericholscher/ericholscher.com/branches{/branch}","tags_url":"https://api.github.com/repos/ericholscher/ericholscher.com/tags","blobs_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/refs{/sha}","trees_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ericholscher/ericholscher.com/statuses/{sha}","languages_url":"https://api.github.com/repos/ericholscher/ericholscher.com/languages","stargazers_url":"https://api.github.com/repos/ericholscher/ericholscher.com/stargazers","contributors_url":"https://api.github.com/repos/ericholscher/ericholscher.com/contributors","subscribers_url":"https://api.github.com/repos/ericholscher/ericholscher.com/subscribers","subscription_url":"https://api.github.com/repos/ericholscher/ericholscher.com/subscription","commits_url":"https://api.github.com/repos/ericholscher/ericholscher.com/commits{/sha}","git_commits_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/commits{/sha}","comments_url":"https://api.github.com/repos/ericholscher/ericholscher.com/comments{/number}","issue_comment_url":"https://api.github.com/repos/ericholscher/ericholscher.com/issues/comments{/number}","contents_url":"https://api.github.com/repos/ericholscher/ericholscher.com/contents/{+path}","compare_url":"https://api.github.com/repos/ericholscher/ericholscher.com/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ericholscher/ericholscher.com/merges","archive_url":"https://api.github.com/repos/ericholscher/ericholscher.com/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ericholscher/ericholscher.com/downloads","issues_url":"https://api.github.com/repos/ericholscher/ericholscher.com/issues{/number}","pulls_url":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls{/number}","milestones_url":"https://api.github.com/repos/ericholscher/ericholscher.com/milestones{/number}","notifications_url":"https://api.github.com/repos/ericholscher/ericholscher.com/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ericholscher/ericholscher.com/labels{/name}","releases_url":"https://api.github.com/repos/ericholscher/ericholscher.com/releases{/id}","deployments_url":"https://api.github.com/repos/ericholscher/ericholscher.com/deployments","created_at":"2013-03-12T01:21:10Z","updated_at":"2016-04-20T17:11:25Z","pushed_at":"2016-07-01T18:00:18Z","git_url":"git://github.com/ericholscher/ericholscher.com.git","ssh_url":"git@github.com:ericholscher/ericholscher.com.git","clone_url":"https://github.com/ericholscher/ericholscher.com.git","svn_url":"https://github.com/ericholscher/ericholscher.com","homepage":null,"size":14689,"stargazers_count":5,"watchers_count":5,"language":"Makefile","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":6,"mirror_url":null,"open_issues_count":2,"forks":6,"open_issues":2,"watchers":5,"default_branch":"master"}},"base":{"label":"ericholscher:master","ref":"master","sha":"23c203551aef25f8e8ecc97b072fb28a0c91e872","user":{"login":"ericholscher","id":25510,"avatar_url":"https://avatars.githubusercontent.com/u/25510?v=3","gravatar_id":"","url":"https://api.github.com/users/ericholscher","html_url":"https://github.com/ericholscher","followers_url":"https://api.github.com/users/ericholscher/followers","following_url":"https://api.github.com/users/ericholscher/following{/other_user}","gists_url":"https://api.github.com/users/ericholscher/gists{/gist_id}","starred_url":"https://api.github.com/users/ericholscher/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ericholscher/subscriptions","organizations_url":"https://api.github.com/users/ericholscher/orgs","repos_url":"https://api.github.com/users/ericholscher/repos","events_url":"https://api.github.com/users/ericholscher/events{/privacy}","received_events_url":"https://api.github.com/users/ericholscher/received_events","type":"User","site_admin":false},"repo":{"id":8717186,"name":"ericholscher.com","full_name":"ericholscher/ericholscher.com","owner":{"login":"ericholscher","id":25510,"avatar_url":"https://avatars.githubusercontent.com/u/25510?v=3","gravatar_id":"","url":"https://api.github.com/users/ericholscher","html_url":"https://github.com/ericholscher","followers_url":"https://api.github.com/users/ericholscher/followers","following_url":"https://api.github.com/users/ericholscher/following{/other_user}","gists_url":"https://api.github.com/users/ericholscher/gists{/gist_id}","starred_url":"https://api.github.com/users/ericholscher/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ericholscher/subscriptions","organizations_url":"https://api.github.com/users/ericholscher/orgs","repos_url":"https://api.github.com/users/ericholscher/repos","events_url":"https://api.github.com/users/ericholscher/events{/privacy}","received_events_url":"https://api.github.com/users/ericholscher/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/ericholscher/ericholscher.com","description":"Personal website.","fork":false,"url":"https://api.github.com/repos/ericholscher/ericholscher.com","forks_url":"https://api.github.com/repos/ericholscher/ericholscher.com/forks","keys_url":"https://api.github.com/repos/ericholscher/ericholscher.com/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ericholscher/ericholscher.com/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ericholscher/ericholscher.com/teams","hooks_url":"https://api.github.com/repos/ericholscher/ericholscher.com/hooks","issue_events_url":"https://api.github.com/repos/ericholscher/ericholscher.com/issues/events{/number}","events_url":"https://api.github.com/repos/ericholscher/ericholscher.com/events","assignees_url":"https://api.github.com/repos/ericholscher/ericholscher.com/assignees{/user}","branches_url":"https://api.github.com/repos/ericholscher/ericholscher.com/branches{/branch}","tags_url":"https://api.github.com/repos/ericholscher/ericholscher.com/tags","blobs_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/refs{/sha}","trees_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ericholscher/ericholscher.com/statuses/{sha}","languages_url":"https://api.github.com/repos/ericholscher/ericholscher.com/languages","stargazers_url":"https://api.github.com/repos/ericholscher/ericholscher.com/stargazers","contributors_url":"https://api.github.com/repos/ericholscher/ericholscher.com/contributors","subscribers_url":"https://api.github.com/repos/ericholscher/ericholscher.com/subscribers","subscription_url":"https://api.github.com/repos/ericholscher/ericholscher.com/subscription","commits_url":"https://api.github.com/repos/ericholscher/ericholscher.com/commits{/sha}","git_commits_url":"https://api.github.com/repos/ericholscher/ericholscher.com/git/commits{/sha}","comments_url":"https://api.github.com/repos/ericholscher/ericholscher.com/comments{/number}","issue_comment_url":"https://api.github.com/repos/ericholscher/ericholscher.com/issues/comments{/number}","contents_url":"https://api.github.com/repos/ericholscher/ericholscher.com/contents/{+path}","compare_url":"https://api.github.com/repos/ericholscher/ericholscher.com/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ericholscher/ericholscher.com/merges","archive_url":"https://api.github.com/repos/ericholscher/ericholscher.com/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ericholscher/ericholscher.com/downloads","issues_url":"https://api.github.com/repos/ericholscher/ericholscher.com/issues{/number}","pulls_url":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls{/number}","milestones_url":"https://api.github.com/repos/ericholscher/ericholscher.com/milestones{/number}","notifications_url":"https://api.github.com/repos/ericholscher/ericholscher.com/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ericholscher/ericholscher.com/labels{/name}","releases_url":"https://api.github.com/repos/ericholscher/ericholscher.com/releases{/id}","deployments_url":"https://api.github.com/repos/ericholscher/ericholscher.com/deployments","created_at":"2013-03-12T01:21:10Z","updated_at":"2016-04-20T17:11:25Z","pushed_at":"2016-07-01T18:00:18Z","git_url":"git://github.com/ericholscher/ericholscher.com.git","ssh_url":"git@github.com:ericholscher/ericholscher.com.git","clone_url":"https://github.com/ericholscher/ericholscher.com.git","svn_url":"https://github.com/ericholscher/ericholscher.com","homepage":null,"size":14689,"stargazers_count":5,"watchers_count":5,"language":"Makefile","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":6,"mirror_url":null,"open_issues_count":2,"forks":6,"open_issues":2,"watchers":5,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/5"},"html":{"href":"https://github.com/ericholscher/ericholscher.com/pull/5"},"issue":{"href":"https://api.github.com/repos/ericholscher/ericholscher.com/issues/5"},"comments":{"href":"https://api.github.com/repos/ericholscher/ericholscher.com/issues/5/comments"},"review_comments":{"href":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/5/comments"},"review_comment":{"href":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/ericholscher/ericholscher.com/pulls/5/commits"},"statuses":{"href":"https://api.github.com/repos/ericholscher/ericholscher.com/statuses/66271735b43d8a518bba9e789f599294176163a1"}}}}
{"actor":{"display_login":"ericholscher"}}