[CentOS-docs] Working Documentation Toolchain [GSoC]
dougal at dougalmatthews.com
Tue Aug 4 14:33:10 UTC 2015
On 4 August 2015 at 14:21, kunaal jain <kunaalus at gmail.com> wrote:
> The basic toolchain is up and running. I encourage community to test
> this workflow once. It is an addition to the existing contributing
> Site: http://clown-olga-13325.bitballoon.com/
> Contributing Docs repo : https://github.com/kunaaljain/test-centos-docs
> Initial Idea : http://wiki.centos.org/GSoC/2015/Ideas#docs-toolchain
> The CentOS Project needs more short-form contributions of content that
> focuses on how-to do things on top of a CentOS Linux installation,
> with a method to push changes in to appropriate and related upstream
> open source projects.
> There is a lot of content scattered across the Internet on how to do
> things with CentOS Linux. The goal of this toolchain is to make it
> easy for people to contribute new, short-form content articles to the
> Project with an ability to push them outward to relevant upstream
> 1. The user authors content in markdown format and creates a pull
> request on Github.
> 2. The backend service mirrors the pull request to pagure and creates a issue.
> 3. The doc is built and a link is provided to preview the doc.
> 5. Staff reviews the docs, gives comments either on pagure or github
> (two way synced)
> 4. Once the staff approves the doc is built and doc site updated.
> 1. A backend server listing to Github and Pagure webhooks and mirroring content.
> 2. A http site displaying the temporary docs.
> 3. A pagure instance
> ==Testing ==
> 1. Fork the https://github.com/kunaaljain/test-centos-docs
> 2. Add new content to docs folder in mardown language.
> 3. Update the mkdocs.yml file and add the new file you just created
> with appropriate heading.
> 4. Create a pull request.
> 5. Within 15-20 seconds, a comment will be made on pull request, with
> the pagure link, which displaying various metadata.
> 6. Once the staff approves, PR is merged and site updated at
Nice, from a very quick test it looks like this works well. I
submitted two changes.
One to update the MkDocs config and the other to add a testing page.
Is there a way for me to see the built version of docs for a pull request? The
build could be successful but something could be wrong with the formatting and
we wouldn't know.
You may want to use a Markdown linting tool, such as markdownlint. It can
easily be included in a Travis test run. We have started to use this
It allows you to help keep the Markdown consistent and it will also flag up some
It looks like I managed to break the integration with this PR.
I branched from another PR that already had an issue on pagure?
Exciting to see this come together, and as always, please do bug me with any
MkDocs questions - I would be very happy to try and resolve any issues.
More information about the CentOS-docs