Move documentation to sphinx

[martin-schulze-vireso]

This is a first step towards hosting version specific documentation as discussed in #318.

• how to update the documentation version automatically with a new release?

• remove warning about unreleased features

• I have reviewed the Contributor Guidelines.

• I have reviewed the Code of Conduct and agree to abide by it

[martin-schulze-vireso]

I just c&p'd most of the readme over into specific subsections of the Sphinx based documentation and replaced the hardcoded bats --help output with dynamic output from a run of the local version. We would still need to create the right environment with sphinx + recommonmark + sphinx-contrib on it and host the output of cd docs; make html; somewhere on the internet to make it readable.

[sublimino]

LGTM, just re-signed and awaiting build

[martin-schulze-vireso]

This is part of getting the documentation onto github pages or read the docs. As is, we would throw away the documentation. Do we have a decision how to display the results @sublimino? We also need to deal with the versioning.

[sublimino]

My only preference is simplicity, is GitHub pages easier perhaps?

[martin-schulze-vireso]

A first try of this can be seen here: https://martin-schulze-vireso.github.io/bats-core/master/

I think the design and ease of versioning integration would be better on read the docs.

[martin-schulze-vireso]

So we won't get the deploy stage green at this point because sphinx will try to build the refs master and version tags but there are non with sphinx documentation so far. Additionally, according to the documentation we need the environment variable GITHUB_TOKEN in travis to be filled with a personal access token with the public_repo scope.

[martin-schulze-vireso]

I moved this over to read the docs: https://bats-core.readthedocs.io/en/feature-documentation_via_sphinx/
This leaves us with the following steps:

• migrate to the actual bats-core/bats-core project (instead of my fork)
• add other maintainers' accounts on read the docs
• add an automation for activating new versions

[martin-schulze-vireso]

This PRs documentation can be seen at https://bats-core--346.org.readthedocs.build/en/346/

[sublimino]

This is ready to merge from my perspective, but there's an unexpected Bash 5-only test failure, which I hope isn't a breaking Bash change but haven't yet debugged.

[martin-schulze-vireso]

From a first glance it looks like GNU parallel is not being found.

[martin-schulze-vireso]

Some days ago bash:5.1 has been released, which shows this error. bash:5.0 does not. I bisected on 5.1 to this commit 3ed95c4. I am looking into the problem but it is unrelated to this PR since it was already present on older commits with bash:5.1

[martin-schulze-vireso]

@sublimino I think this is ready now.

[sublimino]

Thanks @martin-schulze-vireso, I dug through https://github.com/bminor/bash/blob/master/CHANGES but couldn't see anything jump out. Good find.

And great work on getting functional documentation for the project!! 🎆 🎉

[sublimino]

(I had to sign your commits to merge to master @martin-schulze-vireso)

[martin-schulze-vireso]

Thanks @sublimino, signing is not part of my default workflow, so I sometimes forget the final signing rebase.

[jasonkarns]

Thanks @sublimino, signing is not part of my default workflow, so I sometimes forget the final signing rebase.

@martin-schulze-vireso You can configure git to sign by default in just the bats-core repo, if you don't want to sign by default in all your git repos. git config commit.gpgsign true