try to fix docs.rs build failures

pkg-config checks performed by build scripts need to be disabled when
building docs on docs.rs. rust version 1.41 introduced a new `doc` feature
for doc-build mode detection, which replaced the previous ugly `dox`
solution, but unfortunately the official `doc` flag is not passed along to
build scripts (see [1]). a workaround was thus needed which was to use a
cargo.toml entry to force presence of a flag that build scripts can see. i
chose to use the name `doc` for this simply for consistency with the
official flag.

this solution worked fine until the authors of the `quote` crate made a
change (see [2] as pointed out to me at [3]) such that when the `doc` flag
is detected, their macro is substituted with an empty one in the name of
cleaner documentation. this caused docs.rs builds of my crate to fail with
errors (pointing to the `num-derive` crate, which must be the one pulling
in `quote).

the fix it seems is to either (a) simply use a different name, e.g.
"docsrs", or (b) to switch to using the new `DOCS_RS` environment variable
as recommended at [4]. i have chosen to go with the latter.

if the issue at [1] is ever resolved, we could switch back to using
`cfg!(doc)` based detection in the build scripts to disable the check
for local doc building (unnecessary) as well as for docs.rs.

note, when re-reading 7147efa to refresh
my memory i was initially confused by the second to last paragraph, so i'm
going to briefly clarify for my own future benefit: i did not mean that the
name `docsrs` could not have been used for `rustc-args` at that time, i
just meant that i wanted to use the more official name of `doc` in this
case, whilst the `rustdoc-args` entry that uses `docsrs` could not use
`doc` since it would not have compiled with the stable compiler, and the
inconsistency was just going to be temporary since the `rustdoc-args` entry
is just there until the `doc_cfg` feature stablises.

[1]: rust-lang/cargo#8944
[2]: https://docs.rs/quote/1.0.23/src/quote/lib.rs.html#471-477
[3]: rust-num/num-derive#53
[4]: https://docs.rs/about/builds

Author: jnqnfe

pulse-binding-mainloop-glib/CHANGELOG.md

@@ -1,5 +1,6 @@
 # unreleased]
 
+ * Fixed docs.rs build failure.
  * Dropped PA v4 support.
 
 # 2.27.1 (January 9th, 2023)

pulse-binding-mainloop-glib/Cargo.toml

@@ -33,5 +33,4 @@ pa_v6  = [          "libpulse-binding/pa_v6",  "libpulse-mainloop-glib-sys/pa_v6
 [package.metadata.docs.rs]
 all-features = false
 no-default-features = true
-rustc-args = ["--cfg", "doc"]
 rustdoc-args = ["--cfg", "docsrs"]

pulse-binding-simple/CHANGELOG.md

@@ -1,5 +1,6 @@
 # unreleased]
 
+ * Fixed docs.rs build failure.
  * Dropped PA v4 support.
 
 # 2.27.1 (January 9th, 2023)

pulse-binding-simple/Cargo.toml

@@ -32,5 +32,4 @@ pa_v6  = [          "libpulse-binding/pa_v6",  "libpulse-sys/pa_v6",  "libpulse-
 [package.metadata.docs.rs]
 all-features = false
 no-default-features = true
-rustc-args = ["--cfg", "doc"]
 rustdoc-args = ["--cfg", "docsrs"]

pulse-binding/CHANGELOG.md

@@ -1,6 +1,7 @@
 # unreleased]
 
  * Fixed 'double-reference clone' warnings.
+ * Fixed docs.rs build failure.
  * Dropped PA v4 support.
 
 # 2.27.1 (January 9th, 2023)

pulse-binding/Cargo.toml

@@ -37,5 +37,4 @@ pa_v6  = [          "libpulse-sys/pa_v6"]
 [package.metadata.docs.rs]
 all-features = false
 no-default-features = true
-rustc-args = ["--cfg", "doc"]
 rustdoc-args = ["--cfg", "docsrs"]

pulse-sys-mainloop-glib/CHANGELOG.md

@@ -1,5 +1,6 @@
 # unreleased]
 
+ * Fixed docs.rs build failure.
  * Dropped PA v4 support.
 
 # 1.20.1 (January 9th, 2023)

pulse-sys-mainloop-glib/Cargo.toml

@@ -36,5 +36,4 @@ pa_v6  = [          "libpulse-sys/pa_v6"]
 [package.metadata.docs.rs]
 all-features = false
 no-default-features = true
-rustc-args = ["--cfg", "doc"]
 rustdoc-args = ["--cfg", "docsrs"]

pulse-sys-mainloop-glib/build.rs

@@ -1,6 +1,6 @@
 fn main() {
     // Skip pkg-config check if just generating documentation.
-    if cfg!(doc) {
+    if std::env::var_os("DOCS_RS").is_some() {
         return;
     }
 

pulse-sys-simple/CHANGELOG.md

@@ -1,5 +1,6 @@
 # unreleased]
 
+ * Fixed docs.rs build failure.
  * Dropped PA v4 support.
 
 # 1.20.1 (January 9th, 2023)

pulse-sys-simple/Cargo.toml

@@ -35,5 +35,4 @@ pa_v6  = [          "libpulse-sys/pa_v6"]
 [package.metadata.docs.rs]
 all-features = false
 no-default-features = true
-rustc-args = ["--cfg", "doc"]
 rustdoc-args = ["--cfg", "docsrs"]

pulse-sys-simple/build.rs

@@ -1,6 +1,6 @@
 fn main() {
     // Skip pkg-config check if just generating documentation.
-    if cfg!(doc) {
+    if std::env::var_os("DOCS_RS").is_some() {
         return;
     }
 

pulse-sys/CHANGELOG.md

@@ -1,6 +1,7 @@
 # unreleased]
 
  * Fixed warning from clashing namespace exports.
+ * Fixed docs.rs build failure.
  * Dropped PA v4 support.
 
 # 1.20.1 (January 9th, 2023)

pulse-sys/Cargo.toml

@@ -40,5 +40,4 @@ pa_v6  = []
 [package.metadata.docs.rs]
 all-features = false
 no-default-features = true
-rustc-args = ["--cfg", "doc"]
 rustdoc-args = ["--cfg", "docsrs"]

pulse-sys/build.rs

@@ -1,6 +1,6 @@
 fn main() {
     // Skip pkg-config check if just generating documentation.
-    if cfg!(doc) {
+    if std::env::var_os("DOCS_RS").is_some() {
         return;
     }