html-url

Author: burrbull

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+- Add `html-url` option to access `svdtools html` files from docs
 - Move `Reg` in separate file
 - Use `warning` class in docs
 - Refactor `Accessor`

Cargo.lock

@@ -57,6 +57,7 @@ serde_json = { version = "1.0.85", optional = true }
 serde_yaml = { version = "0.9.11", optional = true }
 regex = "1.10.0"
 html-escape = "0.2"
+url = { version = "2.5", features = ["serde"] }
 
 [dependencies.svd-parser]
 features = ["expand"]

Cargo.toml

@@ -35,6 +35,7 @@ pub struct Config {
     pub ident_formats_theme: Option<IdentFormatsTheme>,
     pub field_names_for_enums: bool,
     pub base_address_shift: u64,
+    pub html_url: Option<url::Url>,
 }
 
 #[allow(clippy::upper_case_acronyms)]

src/config.rs

@@ -81,6 +81,11 @@ pub fn render(p_original: &Peripheral, index: &Index, config: &Config) -> Result
         }
     };
 
+    let phtml = config.html_url.as_ref().map(|url| {
+        let doc = format!("See peripheral [structure]({url}#{})", &path.peripheral);
+        quote!(#[doc = ""] #[doc = #doc])
+    });
+
     let per_to_tokens = |out: &mut TokenStream,
                          feature_attribute: &TokenStream,
                          description: &str,
@@ -89,6 +94,7 @@ pub fn render(p_original: &Peripheral, index: &Index, config: &Config) -> Result
                          address: LitInt| {
         out.extend(quote! {
             #[doc = #description]
+            #phtml
             #doc_alias
             #feature_attribute
             pub struct #p_ty { _marker: PhantomData<*const ()> }

src/generate/peripheral.rs

@@ -108,6 +108,7 @@ pub fn render(
             return Err(anyhow!("Incorrect access of register {}", register.name));
         };
 
+        let rpath = path.new_register(&register.name);
         let mut alias_doc = format!(
             "{name} ({accs}) register accessor: {description}{}{}",
             api_docs(
@@ -116,6 +117,9 @@ pub fn render(
                 register.properties.reset_value.is_some(),
                 &mod_ty,
                 false,
+                &register,
+                &rpath,
+                config,
             )?,
             read_action_docs(access.can_read(), register.read_action),
         );
@@ -128,13 +132,7 @@ pub fn render(
             #doc_alias
             pub type #reg_ty = crate::Reg<#mod_ty::#regspec_ty>;
         });
-        let mod_items = render_register_mod(
-            register,
-            access,
-            &path.new_register(&register.name),
-            index,
-            config,
-        )?;
+        let mod_items = render_register_mod(register, access, &rpath, index, config)?;
 
         out.extend(quote! {
             #[doc = #description]
@@ -170,6 +168,9 @@ fn api_docs(
     can_reset: bool,
     module: &Ident,
     inmodule: bool,
+    register: &Register,
+    rpath: &RegisterPath,
+    config: &Config,
 ) -> Result<String, std::fmt::Error> {
     fn method(s: &str) -> String {
         format!("[`{s}`](crate::Reg::{s})")
@@ -211,13 +212,35 @@ fn api_docs(
 
     doc.push_str("See [API](https://docs.rs/svd2rust/#read--modify--write-api).");
 
+    if let Some(url) = config.html_url.as_ref() {
+        let first_idx = if let Register::Array(_, dim) = &register {
+            dim.indexes().next()
+        } else {
+            None
+        };
+        let rname = if let Some(idx) = first_idx {
+            let idx = format!("[{idx}]");
+            rpath.name.replace("[%s]", &idx).replace("%s", &idx)
+        } else {
+            rpath.name.to_string()
+        };
+        // TODO: support html_urls for registers in cluster
+        if rpath.block.path.is_empty() {
+            doc.push_str(&format!(
+                "\n\nSee register [structure]({url}#{}:{})",
+                rpath.peripheral(),
+                rname
+            ));
+        }
+    }
+
     Ok(doc)
 }
 
 pub fn render_register_mod(
     register: &Register,
     access: Access,
-    path: &RegisterPath,
+    rpath: &RegisterPath,
     index: &Index,
     config: &Config,
 ) -> Result<TokenStream> {
@@ -312,7 +335,7 @@ pub fn render_register_mod(
                 access,
                 properties,
                 &mut mod_items,
-                path,
+                rpath,
                 index,
                 config,
             )?;
@@ -361,7 +384,7 @@ pub fn render_register_mod(
 
     let doc = format!(
         "{description}{}{}",
-        api_docs(can_read, can_write, can_reset, &mod_ty, true)?,
+        api_docs(can_read, can_write, can_reset, &mod_ty, true, register, rpath, config)?,
         read_action_docs(access.can_read(), register.read_action),
     );
 

src/generate/register.rs

@@ -267,6 +267,14 @@ Allowed cases are `unchanged` (''), `pascal` ('p'), `constant` ('c') and `snake`
 Useful for soft-cores where the peripheral address range isn't necessarily fixed.
 Ignore this option if you are not building your own FPGA based soft-cores."),
         )
+        .arg(
+            Arg::new("html_url")
+                .long("html-url")
+                .alias("html_url")
+                .help("Path to chip HTML generated by svdtools")
+                .action(ArgAction::Set)
+                .value_name("URL"),
+        )
         .arg(
             Arg::new("log_level")
                 .long("log")