update README and docs

Author: fbdtemme

LICENSE.md LICENSELICENSE.md renamed to LICENSE

@@ -1,10 +1,19 @@
 ![](docs/images/bencode.svg)
 
-![build](https://github.com/fbdtemme/bencode/workflows/build/badge.svg?branch=master)
+[![build](https://github.com/fbdtemme/bencode/workflows/build/badge.svg?branch=master)](https://github.com/fbdtemme/bencode/actions?query=workflow%3Abuild)
+[![docs](https://github.com/fbdtemme/bencode/workflows/documentation/badge.svg?branch=master)](https://fbdtemme.github.io/bencode/)
 [![Codacy Badge](https://api.codacy.com/project/badge/Grade/5cc3eec94d8a486dab62afeab5130def)](https://app.codacy.com/manual/floriandetemmerman/bencode?utm_source=github.com&utm_medium=referral&utm_content=fbdtemme/bencode&utm_campaign=Badge_Grade_Dashboard)
 [![codecov](https://codecov.io/gh/fbdtemme/bencode/branch/master/graph/badge.svg)](https://codecov.io/gh/fbdtemme/bencode)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+[**Features**](#Features) |
+[**Status**](#Status) |
+[**Documentation**](#Documentation) | 
+[**Examples**](#Examples) |
+[**Building**](#Building) | 
+[**Integration**](#Integration) |
+[**License**](#License)
+
 A header-only C++20 bencode serialization/deserialization library.
 
 ## Features
@@ -15,24 +24,16 @@ A header-only C++20 bencode serialization/deserialization library.
 *  Support for serializing/deserializing to/from user-defined types. 
 *  Parse directly to custom types by satisfying the `EventConsumer` concept.
 *  Throwing and non throwing variants of common functions.
-*  Iterative parsing to be safe against stack overflow attacks.
-
-## Documentation
+*  Iterative parsing to protect against stack overflow attacks.
 
-Documentation is available on the [bencode GitHub pages](https://fbdtemme.github.io/bencode/)
+## Status
 
-## Requirements
+This library is still under development, but should be fairly stable. 
+The API may change at any release prior to 1.0.0.
 
-This project requires C++20. 
-Currently only GCC 10 is supported.
-
-This library depends on following projects:
-*  [Catch2](https://github.com/catchorg/Catch2)
-*  [fmt](https://github.com/fmtlib/fmt)
-*  [Microsoft GSL](https://github.com/microsoft/GSL)
-*  [expected-lite](https://github.com/martinmoene/expected-lite)
+## Documentation
 
-All dependencies can be fetched from github during configure time or can be installed manually.
+Documentation is available on the [bencode GitHub pages](https://fbdtemme.github.io/bencode/)
 
 ## Examples
 
@@ -75,7 +76,9 @@ auto v2 = get_integer(b[1]);
 
 Serialize to bencode using `bvalue`.
 ```cpp
-#include <bencode/bvalue.hpp> 
+#include <iostream>
+#include <bencode/bvalue.hpp>
+#include <bencode/encode.hpp>
 
 bc::bvalue b {
   {"foo", 1},
@@ -90,8 +93,10 @@ bc::encode_to(std::cout, b);
 Serialize to bencode using `encoder`
 
 ```cpp
-#include <bencode/encode.hpp> 
-#include <bencode/traits/vector.hpp> 
+#include <iostream>
+#include <vector>
+#include <bencode/encode.hpp>           // bc::encoder
+#include <bencode/traits/vector.hpp>    // support for serializating std::vector
 
 bc::encoder es(std::cout);
 
@@ -105,3 +110,75 @@ es << bc::begin_dict
 ```
 
 For more examples see the [documentation](https://fbdtemme.github.io/bencode/) 
+
+## Building
+
+This project requires C++20. 
+Currently only GCC 10 is supported.
+
+This library depends on following projects:
+*  [Catch2](https://github.com/catchorg/Catch2)
+*  [fmt](https://github.com/fmtlib/fmt)
+*  [Microsoft GSL](https://github.com/microsoft/GSL)
+*  [expected-lite](https://github.com/martinmoene/expected-lite)
+
+All dependencies can be fetched from github during configure time or can be installed manually.
+
+The tests can be built as every other project which makes use of the CMake build system.
+
+```{bash}
+mkdir build
+cd build
+cmake -DCMAKE_BUILD_TYPE=Debug ..
+make 
+```
+
+## Integration
+
+You can use the `bencode::bencode` interface target in CMake.
+The library can be located with `find_package`.
+
+```cmake
+# CMakeLists.txt
+find_package(bencode REQUIRED)
+...
+add_library(foo ...)
+...
+target_link_libraries(foo INTERFACE bencode::bencode)
+```
+
+The source tree can be included in your project and added to your build with `add_subdirectory`.
+
+```cmake
+# CMakeLists.txt
+# Disable building tests and benchmarks.
+set(BENCODE_BUILD_TESTS OFF)
+set(BENCODE_BUILD_BENCHMARKS OFF)
+
+add_subdirectory(bencode)
+...
+add_library(foo ...)
+...
+target_link_libraries(foo INTERFACE bencode::bencode)
+```
+
+You can also use `FetchContent` to download the code from github.
+    
+```cmake
+# CMakeLists.txt
+include(FetchContent)
+
+FetchContent_Declare(bencode
+  GIT_REPOSITORY https://github.com/fbdtemme/bencode.git
+  GIT_TAG "master")
+
+FetchContent_MakeAvailable(bencode)
+...
+add_library(foo ...)
+...
+target_link_libraries(foo INTERFACE bencode::bencode)
+```
+
+## License
+
+Distributed under the MIT license. See `LICENSE` for more information.

README.md

@@ -27,9 +27,10 @@ The source tree can be included in your project and included with :code:`add_sub
 .. code-block::
 
     # CMakeLists.txt
-    # Typically you don't care so much for a third party library's tests to be
-    # run from your own project's code.
+    # Disable building tests and benchmarks.
     set(BENCODE_BUILD_TESTS OFF)
+    set(BENCODE_BUILD_BENCHMARKS OFF)
+
     add_subdirectory(bencode)
     ...
     add_library(foo ...)
@@ -49,5 +50,7 @@ Embedded (FetchContent)
       GIT_TAG "master")
 
     FetchContent_MakeAvailable(bencode)
-
+    ...
+    add_library(foo ...)
+    ...
     target_link_libraries(foo INTERFACE bencode::bencode)

docs/getting_started/integration.rst

@@ -5,6 +5,8 @@ bencode
 
 A C++20 bencode serialisation/deserialization library.
 
+Source code is hosted on `GitHub <https://github.com/fbdtemme/bencode>`_ under the :ref:`MIT license <license>`.
+
 .. note:: This documentation site is under construction.
 
 Content

docs/index.rst

@@ -1,6 +1,8 @@
 License
 =======
 
+.. _license:
+
 This project is licensed under the `MIT license <https://opensource.org/licenses/MIT>`_:
 
 .. pull-quote::