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.
What you'll learn
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.
Table of contents
- Introduction 2m
- Git and GitHub: Introduce and Install 4m
- Create and Load GitHub Repository for the Source Code 4m
- Set up Read the Docs Hosting 2m
- Continuous Integration/continuous Delivery Explained 2m
- Set Continuous Integration/continuous Delivery Explained up CI/CD on Read the Docs 4m
- Pull Requests Explained 2m
- Configure GitHub to Require Pull Requests to Master 4m
- Submit a Change via Pull Request 3m
- Approve and Merge the Pull Request 2m
- Summary 1m
- Introduction 1m
- Custom CSS: The Approach 1m
- Why Custom CSS: Control Horizontal Scroll on Tables 3m
- Add Custom CSS to the Project 2m
- Add Markdown Support and a Markdown Document 3m
- Versions: Introduction 1m
- Enable Versions with a Long-lived Branch 2m
- Verify Version Behavior by Rolling a Change Through Branches 3m
- Summary 1m
- Introduction 2m
- Hosting Options Explored 2m
- Set up Repo in Visual Studio Team Services (VSTS) 2m
- VSTS Build Agents: Explanation and Process Overview 1m
- Set up a Local VSTS Build Agent 5m
- Create VSTS Build Definition and Build the Docs 3m
- Set up VSTS Deploy Agent 1m
- Create VSTS Release Definition and Execute It 4m
- Set up CI/CD with VSTS, Push Change for Edit on GitHub 5m
- Conclusion 1m