Add docsrs feature gating

As we do in `rust-bitcoin` add a compiler conditional configuration
option `docsrs` to add feature gating to the docrs build.

Fix and improve the rustdocs while we are at it.

Add docs build to CI script but do not enable it in the github actions
yet.

Fix: rust-bitcoin#75

Author: tcharding

contrib/test.sh

@@ -32,6 +32,17 @@ if [ "$DO_FMT" = true ]; then
     cargo fmt --check
 fi
 
+# Build the docs if told to (this only works with the nightly toolchain)
+if [ "$DO_DOCSRS" = true ]; then
+    RUSTDOCFLAGS="--cfg docsrs -D warnings -D rustdoc::broken-intra-doc-links" cargo +nightly doc --all-features
+fi
+
+# Build the docs with a stable toolchain, in unison with the DO_DOCSRS command
+# above this checks that we feature guarded docs imports correctly.
+if [ "$DO_DOCS" = true ]; then
+    RUSTDOCFLAGS="-D warnings" cargo +stable doc --all-features
+fi
+
 # Check without features.
 cargo build --no-default-features
 cargo test --no-default-features