Add Travis-CI tests for docs

[AyanSinhaMahapatra]

This PR adds Travis-CI checks for documentation, similar to that in aboutcode. It also adds the requirements file for ReadTheDocs build and minor doc style fixes.

[AyanSinhaMahapatra]

@pombredanne @MaJuRG The ./configure fails for changes made in setup.py, and I need help with that.

[pombredanne]

@MaJuRG any idea why this fails?

[steven-esser]

@AyanSinhaMahapatra Yes

[AyanSinhaMahapatra]

I think packages mentioned in setup.py has to have their corresponding wheels located in thirdparty/. Now, do we actually need to do that in this case? If we want to install sphinx, doc8 just for the tests, then we can just run pip install from the CI jobs, that is just placing them explicitly in the .travis.yml file. Should I just do that instead of trying to get Sphinx and other libraries installed in the virtualenv created by scancode at the time of configuring?

[AyanSinhaMahapatra]

Sorry, Updated the comment.

[steven-esser]

@AyanSinhaMahapatra In this case I think we will need the .whl files added to the thirdparty/ directory

We want people to be able to build the docs locally as well, not just on the CI systems.

ScanCode is a bit unconventional in this way (i.e. having to add deps manually etc), but ScanCode is used in many places where there may be no external internet connection so we want to be fully self-contained for these types of scenarios.

[AyanSinhaMahapatra]

@MaJuRG I see there are .LICENSE and .ABOUT files also, along with the .whl files. So the LICENSE file is the same as the LICENSE file inside the wheel (and renamed similar to wheel name)? Also, where do I get corresponding ABOUT files?

[AyanSinhaMahapatra]

Also, Sphinx itself has another dozen requirements. Do I add wheels for them also?

[steven-esser]

@AyanSinhaMahapatra I believe we will want to add the sphix deps as well, if they are not already present in the thirdparty directory.

We probably do not need to worry about the .LICENSE files for sphinx and its deps, BUT we will want to have ABOUT files for these. You can use the existing ABOUT files in the thirdparty repo as a skeleton of sorts.

See: https://github.com/nexB/aboutcode-toolkit/blob/develop/SPECIFICATION.rst for details on ABOUT files

[AyanSinhaMahapatra]

@pombredanne @MaJuRG Since we are enabling local documentation builds by installing dependencies in the time of initial configuration, isn't it a good idea also build the documentation then inside ./configure (command is make html, inside docs) and maybe add a CLI option into scancode like --open-docs to open the locally available documentation (command is see docs/build/html/index.html) in a browser window?

[steven-esser]

@AyanSinhaMahapatra Not sure that we want to build docs have automatically on ./configure.

I think having the users run make html in the docs/ dir is enough, as long as we document this somewhere.

[steven-esser]

This looks good to me @AyanSinhaMahapatra, however the travis build is failing for some reason.

I think it got hung up on installing some base packages for macOS. I think if you re-trigger the build we should be good to go.

[AyanSinhaMahapatra]

I think having the users run make html in the docs/ dir is enough, as long as we document this somewhere.

Sure! I'll add that somewhere. Triggering a rebuild so the tests pass.

[AyanSinhaMahapatra]

@MaJuRG Checks Passed.

[steven-esser]

@pombredanne This looks good to me, can you take a look and merge?

[pombredanne]

All good! Thanks!