Documentation migrate to docs.rs hosted

This change migrates all the documentation from dalek.rs
to docs.rs hosted and fixed the backend documentation
generation that was broken.

CHANGELOG.md

@@ -5,6 +5,8 @@ major series.
 
 ## 4.x series
 
+* Migrate documentation to docs.rs hosted
+* Fix backend documentation generation
 * Deprecate `EdwardsPoint::hash_from_bytes` and rename it `EdwardsPoint::nonspect_map_to_curve`
 * Fix panic when `Ristretto::double_and_compress_batch` receives the identity point
 * Remove `byteorder` dependency

Cargo.toml

@@ -24,9 +24,8 @@ exclude = [
 ]
 
 [package.metadata.docs.rs]
-# Disabled for now since this is borked; tracking https://github.com/rust-lang/docs.rs/issues/302
-# rustdoc-args = ["--html-in-header", ".cargo/registry/src/github.com-1ecc6299db9ec823/curve25519-dalek-0.13.2/rustdoc-include-katex-header.html"]
-features = ["nightly", "simd_backend"]
+rustdoc-args = ["--html-in-header", "docs/assets/rustdoc-include-katex-header.html", "--cfg", "docsrs"]
+features = ["nightly", "simd_backend", "packed_simd"]
 
 [badges]
 travis-ci = { repository = "dalek-cryptography/curve25519-dalek", branch = "master"}

Makefile

@@ -1,8 +1,8 @@
-FEATURES := nightly simd_backend
+FEATURES := nightly simd_backend packed_simd
 
 doc:
-	cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html
+	cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --cfg docsrs
 
 doc-internal:
-	cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --document-private-items
+	cargo +nightly rustdoc --features "$(FEATURES)" -- --html-in-header docs/assets/rustdoc-include-katex-header.html --document-private-items --cfg docsrs
 

README.md

@@ -246,6 +246,6 @@ contributions.
 [docs-external]: https://doc.dalek.rs/curve25519_dalek/
 [docs-internal]: https://doc-internal.dalek.rs/curve25519_dalek/
 [criterion]: https://github.com/japaric/criterion.rs
-[parallel_doc]: https://doc-internal.dalek.rs/curve25519_dalek/backend/vector/avx2/index.html
+[parallel_doc]: https://docs.rs/curve25519-dalek/latest/curve25519_dalek/backend/vector/index.html
 [subtle_doc]: https://doc.dalek.rs/subtle/
 [fiat-crypto]: https://github.com/mit-plv/fiat-crypto

docs/parallel-formulas.md

@@ -327,7 +327,7 @@ There are several directions for future improvement:
 [sandy2x]: https://eprint.iacr.org/2015/943.pdf
 [avx2trac]: https://trac.torproject.org/projects/tor/ticket/8897#comment:28
 [hwcd08]: https://www.iacr.org/archive/asiacrypt2008/53500329/53500329.pdf
-[curve_models]: https://doc-internal.dalek.rs/curve25519_dalek/backend/serial/curve_models/index.html
+[curve_models]: https://docs.rs/dalek-test-curve-docs/latest/dalek_test_curve_docs/backend/serial/curve_models/index.html
 [bbjlp08]: https://eprint.iacr.org/2008/013
 [cmo98]: https://link.springer.com/content/pdf/10.1007%2F3-540-49649-1_6.pdf
 [intel]: https://software.intel.com/sites/default/files/managed/9e/bc/64-ia-32-architectures-optimization-manual.pdf

src/backend/mod.rs

@@ -36,18 +36,5 @@
 
 pub mod serial;
 
-#[cfg(any(
-    all(
-        feature = "simd_backend",
-        any(target_feature = "avx2", target_feature = "avx512ifma")
-    ),
-    all(feature = "nightly", rustdoc)
-))]
-#[cfg_attr(
-    feature = "nightly",
-    doc(cfg(any(all(
-        feature = "simd_backend",
-        any(target_feature = "avx2", target_feature = "avx512ifma")
-    ))))
-)]
+#[cfg(any(feature = "simd_backend", docsrs))]
 pub mod vector;

src/backend/serial/curve_models/mod.rs

@@ -148,6 +148,7 @@ use crate::traits::ValidityCheck;
 ///
 /// More details on the relationships between the different curve models
 /// can be found in the module-level documentation.
+#[allow(missing_docs)]
 #[derive(Copy, Clone)]
 pub struct ProjectivePoint {
     pub X: FieldElement,
@@ -199,6 +200,7 @@ impl Zeroize for AffineNielsPoint {
 /// More details on the relationships between the different curve models
 /// can be found in the module-level documentation.
 #[derive(Copy, Clone)]
+#[allow(missing_docs)]
 pub struct ProjectiveNielsPoint {
     pub Y_plus_X: FieldElement,
     pub Y_minus_X: FieldElement,

src/backend/serial/scalar_mul/mod.rs

@@ -17,8 +17,10 @@
 //! scalar multiplication implementations, since it only uses one
 //! curve model.
 
+#[allow(missing_docs)]
 pub mod variable_base;
 
+#[allow(missing_docs)]
 pub mod vartime_double_base;
 
 #[cfg(feature = "alloc")]

src/backend/serial/scalar_mul/precomputed_straus.rs

@@ -25,6 +25,7 @@ use crate::window::{NafLookupTable5, NafLookupTable8};
 #[allow(unused_imports)]
 use crate::prelude::*;
 
+#[allow(missing_docs)]
 pub struct VartimePrecomputedStraus {
     static_lookup_tables: Vec<NafLookupTable8<AffineNielsPoint>>,
 }

src/backend/vector/ifma/mod.rs

@@ -9,8 +9,10 @@
 
 #![doc = include_str!("../../../../docs/ifma-notes.md")]
 
+#[allow(missing_docs)]
 pub mod field;
 
+#[allow(missing_docs)]
 pub mod edwards;
 
 pub mod constants;

src/backend/vector/mod.rs

@@ -11,29 +11,29 @@
 
 #![doc = include_str!("../../../docs/parallel-formulas.md")]
 
-#[cfg(not(any(target_feature = "avx2", target_feature = "avx512ifma", rustdoc)))]
+#[cfg(not(any(target_feature = "avx2", target_feature = "avx512ifma", docsrs)))]
 compile_error!("simd_backend selected without target_feature=+avx2 or +avx512ifma");
 
 #[cfg(any(
     all(target_feature = "avx2", not(target_feature = "avx512ifma")),
-    rustdoc
+    docsrs
 ))]
-#[doc(cfg(all(target_feature = "avx2", not(target_feature = "avx512ifma"))))]
 pub mod avx2;
 #[cfg(any(
     all(target_feature = "avx2", not(target_feature = "avx512ifma")),
-    rustdoc
+    docsrs
 ))]
 pub(crate) use self::avx2::{
     constants::BASEPOINT_ODD_LOOKUP_TABLE, edwards::CachedPoint, edwards::ExtendedPoint,
 };
 
-#[cfg(any(target_feature = "avx512ifma", rustdoc))]
-#[doc(cfg(target_feature = "avx512ifma"))]
+#[cfg(any(target_feature = "avx512ifma", docsrs))]
 pub mod ifma;
 #[cfg(target_feature = "avx512ifma")]
 pub(crate) use self::ifma::{
     constants::BASEPOINT_ODD_LOOKUP_TABLE, edwards::CachedPoint, edwards::ExtendedPoint,
 };
 
+#[cfg(any(target_feature = "avx2", target_feature = "avx512ifma", docsrs))]
+#[allow(missing_docs)]
 pub mod scalar_mul;

src/edwards.rs

@@ -85,7 +85,7 @@
 //! successful decompression of a compressed point, or else by
 //! operations on other (valid) `EdwardsPoint`s.
 //!
-//! [curve_models]: https://doc-internal.dalek.rs/curve25519_dalek/backend/serial/curve_models/index.html
+//! [curve_models]: https://docs.rs/curve25519-dalek/latest/curve25519-dalek/backend/serial/curve_models/index.html
 
 // We allow non snake_case names because coordinates in projective space are
 // traditionally denoted by the capitalisation of their respective

src/lib.rs

@@ -13,13 +13,13 @@
 #![cfg_attr(feature = "nightly", feature(test))]
 #![cfg_attr(feature = "nightly", feature(doc_cfg))]
 #![cfg_attr(feature = "simd_backend", feature(stdsimd))]
-
 //------------------------------------------------------------------------
 // Documentation:
 //------------------------------------------------------------------------
-
 #![deny(missing_docs)]
-#![doc(html_logo_url = "https://doc.dalek.rs/assets/dalek-logo-clear.png")]
+#![doc(
+    html_logo_url = "https://cdn.jsdelivr.net/gh/dalek-cryptography/curve25519-dalek/docs/assets/dalek-logo-clear.png"
+)]
 #![doc(html_root_url = "https://docs.rs/curve25519-dalek/4.0.0-pre.2")]
 #![doc = include_str!("../README.md")]
 
@@ -72,9 +72,13 @@ pub mod traits;
 pub(crate) mod field;
 
 // Arithmetic backends (using u32, u64, etc) live here
+#[cfg(docsrs)]
+pub mod backend;
+#[cfg(not(docsrs))]
 pub(crate) mod backend;
 
 // Crate-local prelude (for alloc-dependent features like `Vec`)
+
 pub(crate) mod prelude;
 
 // Generic code for window lookups