[CentOS-docs] Working Documentation Toolchain [GSoC]

Tue Aug 4 14:33:10 UTC 2015
Dougal Matthews <dougal at dougalmatthews.com>

On 4 August 2015 at 14:21, kunaal jain <kunaalus at gmail.com> wrote:
> Hi,
>
> The basic toolchain is up and running. I encourage community to test
> this workflow once. It is an addition to the existing contributing
> mediums.
>
> Site: http://clown-olga-13325.bitballoon.com/
> Contributing Docs repo : https://github.com/kunaaljain/test-centos-docs
>
> ==AIM==
>
> 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
> projects.
>
> ==Workflow==
>
> 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.
>
> ==Infra==
>
> 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
> http://clown-olga-13325.bitballoon.com/

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
with MkDocs.
It allows you to help keep the Markdown consistent and it will also flag up some
common errors.

It looks like I managed to break the integration with this PR.
Presumably because
I branched from another PR that already had an issue on pagure?
https://github.com/kunaaljain/test-centos-docs/pull/19

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.

Dougal