Update documentation

[GPMueller]

On PR #23, a lot of changes were made and the documentation needs to be updated accordingly.

• update Readme with better example of small config file and a full config file
• update Readme and make it more compact
• add docs folder and readthedocs
• add step by step incremental guide to documentation in docs folder
• add note that boost filesystem can be built with this, as a non-trivial example of a real-world application

[GPMueller]

Maybe something like this?

[mytarget]
output_name = "myexe"      # will get pre- and suffix according to system
target_type = "executable" # or "shared library", "static library", "header only"

# target sources can be downloaded
external = true # default:false
url = "https://github.com/trick-17/mylib"
version = 1.1 # will try to git checkout [v]1.1[.*]

# source directory is taken relative to the configuration file,
# or relative to the download directory if the target is external
directory = "relativedir"

# other targets that mytarget should be linked to
dependencies = ["myothertarget"]

# finer control over where source files are and what should be in-/excluded
[mytarget.sources]
file_extensions = [".hpp", ".cpp"]
include_directories = ["include"]
source_directories  = ["src"]

# should this really exist?
[hello.properties]
cpp_version = 17

[NOhs]

I think it isn't a smart choice given all the things clang-build does automatically to have this as a first example. I know we also need to show that more complex scenarios are still easy to handle, but we should also really emphasize how little configuration most simple projects need.

[NOhs]

I would also add a part in the documentation that is aimed at people that try to extend clang-build or integrate it into their projects. I find this is often lacking for projects and this limits contributions.

[NOhs]

Finally, I would not include adding all the documentation in the PR. We can have a separate one for this.

[NOhs]

I like the tqdm readme: https://github.com/tqdm/tqdm, maybe we could try something similar

[GPMueller]

I agree on the focus and adding a proper "how to use it in your project". The full reference for the config file should go in the docs folder, but the readme could show that even a full target config will not generally be very large.

The tqdm Readme is a bit large, but well structured. At the very least we should have a similar table of contents.

Regarding the PR I think it's fine if it just updates things in the Readme, which have become outdated (such as curling the script).

[NOhs]

I especially like the introduction section of the tqdm readme. We could have a similar gif were we have a terminal, print the folder structure as a tree (something like src and include) and then type clang-build and it will create the executable. Finally calling the executable which will print out something.

[GPMueller]

The command tree will print the source tree nicely:

See https://gist.github.com/paulirish/b6cf161009af0708315c on how to create a gif.

[NOhs]

That is a nice screen capture you created :). I really like it. Should definitely go into the readme.

[NOhs]

Oh and this might be nit-picky but can we increase the visual fidelity of the gif a bit? It seems a bit low-res and has some visible artifacts.

[NOhs]

I started with the webpage. It is on the branch documentation. I also activated that branch temporarily on readthedocs: https://clang-build.readthedocs.io/en/documentation/

[GPMueller]

I think three things remain to do on the documentation branch:

• make the Readme more compact and link to readthedocs
• write a more concise and clearer explanation of the motivation and philosophy
• cross-link between the rst files and improve the toc (also, https://clang-build.readthedocs.io/en/latest/ does not give the expected index page)
• note real-world project example: boost filesystem

We should describe more clearly why we don't allow much scripting and how we believe C++ code should be built.

[GPMueller]

For some reason, the rst file is not being parsed appropriately, see e.g. https://clang-build.readthedocs.io/en/documentation/user_guide/multiple_projects.html

The gif has been inserted and is shown correctly on GH: https://github.com/Trick-17/clang-build/tree/documentation

Should consult http://openalea.gforge.inria.fr/doc/openalea/doc/_build/html/source/sphinx/rest_syntax.html

Edit: fixed with 37a028b.