Build or Contribute to Documentation with a Git-based Workflow

Read the Docs is a great documentation platform used by many open source projects. This course teaches you how to create your own documentation project, use the reStructuredText markup language, and the basics of Git-based workflow for pull requests.
Course info
Rating
(11)
Level
Beginner
Updated
Dec 6, 2017
Duration
2h 0m
Table of contents
Course Overview
Free up Your Time or Give a Little Back: A Case for Documentation
Getting Started: Create Your Documentation Project
Leveraging the Power of reStructuredText Markup
Automating Updates with a Streamlined Workflow
Content That Goes Beyond reStructuredText
Hosting Alternatives for the Documentation and Its Source
Description
Course info
Rating
(11)
Level
Beginner
Updated
Dec 6, 2017
Duration
2h 0m
Description

Documentation of software applications and packages is often an afterthought at best, and frequently forgotten altogether. Putting together some good, easy-to-navigate documentation that can be updated by the community in a controlled fashion can really help avoid questions and make your application or package easier to use. In this course, Build or Contribute to Documentation with a Git-based Workflow, you'll explore a couple of options available to you, and then go into a full solution using Read the Docs by creating a documentation project. First, you'll learn about the reStructuredText syntax for some of the key elements you’ll likely want to include in your documentation. Then, you’ll delve into setting up a CI/CD workflow by putting your documentation in GitHub and show the standard workflow for pull requests. Additionally, you'll discover how to customize the look of your documentation, use Markdown, and have different versions of your documentation. Finally, you'll explore self-hosting documentation and code in the event that a Read the Docs hosted site is not a good option for you. By the end of this course, you'll have the necessary knowledge to efficiently create your own documentation projects, contribute to open source documentation, make pull requests, and know the hosting options available to you.

About the author
About the author

Full-stack developer, architect using the Microsoft stack and other key tools to create awesome solutions.

More from the author
Section Introduction Transcripts
Section Introduction Transcripts

Course Overview
Hi everyone, my name is Erik Dahl and welcome to my course Build or Contribute to Documentation with a Git-based Workflow. I'm a principle architect at Real Page. Do you author projects that other developers will be using and ever have to answer questions about your project? Or have you used an open source project and needed to pose questions in a forum or on Stack Overflow to get an answer about how to use the project in your application? If you answered yes to either of these questions, then this course is for you. We'll be addressing both the creation of a documentation project from scratch, as well as making updates or contributions using a Git-based workflow, which will include pull requests and continuous integration and delivery. No prior Git experience is assumed, so if you've been looking for that course that can help you hit the ground running with Git and pull requests, you've found it. Some of the major topics that we'll cover include setting up a brand new documentation project, learning the ReStructured Text markup syntax, setting up continuous integration and delivery, and reviewing the full Git workflow for a contribution via pull request. By the end of this course you'll know how to create your own doc project, how to contribute to open source docs, how to make pull requests, and even what hosting options are available for your source code and documentation site. I hope you'll join me on this exciting exploration of documentation tech and Git workflows with the Build or Contribute to Documentation With the Git-based workflow course, right here at Pluralsight.

Getting Started: Create Your Documentation Project
A couple of installs and using the ReadTheDocs command line interface to create your documentation project will have you up and editing real documentation in a matter of minutes. I'm Erik Dahl and in this module we're going to jump right in by setting up a few requirements and generating a documentation project that we can edit and run locally. Let's go.

Leveraging the Power of reStructuredText Markup
Having a documentation project is great, but not very helpful if you can't utilize the different constructs of a language to help highlight important points and create some structure to the information you're trying to convey. Hi, it's Erik again, and in this module we're going to explore how the ReStructured Text markup language is used to do just that. Here we go. Once again, this module will be slide light and demo heavy. The whole purpose of this module is to get you up and running with ReStructured Text quickly, so we'll be covering most of what you'll need to do just that. The information we present here will enable you to create a rich documentation site that will engage readers. There are some options and constructs that we won't be covering, and for the full details of the options available, you can jump over to the sphinx docs themselves if you find the need. They are at the sphinx-doc URL I'm showing here. To get us started, we'll look first at the table of contents tree, or TOC tree, that is part of the sphinx framework. We'll use this on the main index page to provide a quick jumping point to the other documents in our site. To that end, I've already created some additional rst files in our doc project and they're empty, save a little hello from here statement. We'll use those empty docs as the items in our table of contents and see how they work. We'll move on to use restructured text to create various kinds of page elements, from formatted text to including code snippets, tables, numbered and bulleted lists, and other kinds of stuff. Finally, we'll learn how to get hyperlinks onto our pages so we can jump to other locations, whether they're outside our documentation site, pages within it, or specific locations that we define.

Automating Updates with a Streamlined Workflow
So far we've learned how to create a doc project and also to create content. That's all great, but we're just getting started. It's Erik again and in this module we'll set up Read The Docs hosting for our project, along with the typical Git workflow to control and simplify the way that updates get made to the docs. Let's dive in. This module will cover four major topics regarding our doc project. We'll start with Git and GitHub. We'll discuss what each of those things are and get setup so that we can use both of them. And then we'll set up what's called the repository for our code. Feel free to skip round if you know this stuff. I'm including it because I wish I could have seen something simple like this awhile ago. We'll move on to Read The Docs where we'll get logged in and link our Read The Docs account to our GitHub account and the repository for our docs. We'll also set up CI/CD here to automate some things, and if you don't know what that is, we'll quickly explain it. The remainder of this module will be spent covering pull requests, what they are and how to configure our doc repo to require them. Then we'll walk through the actual workflow for a pull request from the perspective of the creator and the reviewer. If you're already familiar with Git and Pull requests, that's great, but if you're new to them and they sound like mysterious things that only hardcore open source people know about, this module ought to remove that mystery and leave you comfortable to create your own pull request should the need arise.

Content That Goes Beyond reStructuredText
In this course you've learned about the ReadTheDocs platform using ReStructured Text and setting up workflow with automated CI/CD using the GitHub and ReadTheDocs integration. This is enough to get you rolling in creating your own docs, but getting a real project out there sometimes presents some additional challenges, right? Hi, it's Erik and in this module we'll explore some of those curveballs you may have to deal with and how to address them. You can look at the clip titles and pick and choose the ones that apply to you and ignore the rest, I won't be offended. The first of the challenges we'll address is adding some custom CSS into the mix. You may want to tweak the colors of something or control the layout of an element a little differently than it would happen by default and custom CSS can help you with that. The next item we'll cover is enabling markdown files in addition to ReStructured Text. Markdown is a popular markup language used on GitHub and other places and if you have some existing markdown docs, enabling them to be included in your doc projects may expedite delivery for you. Lastly, we'll look at supporting different versions of the documentation and how to make that work.

Hosting Alternatives for the Documentation and Its Source
So far in this course everything we've done has used cloud hosting from GitHub and ReadTheDocs. org. While this may work fine in many situations and offers its conveniences, it may not fit your requirements for hosting source code or for controlling the accessibility of the documentation site itself. It's Erik again and in this module we'll be having a look at options available to us in these areas and actually setting up an alternative to GitHub and ReadTheDocs that should provide sufficient guidance to help direct you in most any other combination of options you might choose. We'll start the module by discussing the options available for both source hosting and documentation site hosting. The available options should have something that will meet your needs. Then the rest of the module will be spent specifically setting up the whole process with Visual Studio Team Services, or VSTS. We'll continue to use Git for version control, but when we get away from GitHub and ReadTheDocs, we'll have to do some extra work to get both builds and deployments set up. We'll be configuring VSTS on the cloud to build the docs on my local machine by using what's called a build agent. Then we'll set up a deployment from VSTS to my local machine as a host for the doc website. We'll also enable CI/CD here, just like we had with GitHub and ReadTheDocs. This flow may not be exactly what you would want to use for your setup, but if you recall what we've already learned about Read The Docs itself, are familiar with the other options we'll discuss here in a sec, and then stay with me while we learn the techniques to set up VSTS, you should have everything you need to know to host source or doc websites wherever it makes sense for you.