Process documentation from input specs to ensure correct formatting and working links

[mpeddada1]

• Protect all code blocks with norust #92
  • Currently, we are identifying code examples in proto comments based on the presence of blockquotes and indentation. However, this is not always applicable for cases such as https://github.com/googleapis/googleapis/blob/3cef095370b3176f67542e527ffde81e019df091/google/type/phone_number.proto#L42-L48 where the code example is variably indented (like in Java). This results in norust being added to some lines in the code example but not others. See

    google-cloud-rust/src/generated/type/src/model.rs

    Lines 823 to 838 in 2c15c46

    	/// For instance, in Java this would be:
    	///
    	/// com.google.type.PhoneNumber wireProto =
    	/// ```norust
    	/// com.google.type.PhoneNumber.newBuilder().build();
    	/// ```
    	/// com.google.i18n.phonenumbers.Phonenumber.PhoneNumber phoneNumber =
    	/// ```norust
    	/// PhoneNumberUtil.getInstance().parse(wireProto.getE164Number(), "ZZ");
    	/// ```
    	/// if (!wireProto.getExtension().isEmpty()) {
    	/// ```norust
    	/// phoneNumber.setExtension(wireProto.getExtension());
    	/// ```
    	/// }
    	///

    .
  • Potential options:
    • Take additional heuristics into account to identify code samples (semicolons, braces). May not be sustainable especially when we have examples like this as different languages use different code styles.
    • Leverage https://github.com/yuin/goldmark as mentioned in Protect all code blocks with norust #92 to parse code blocks based on CommonMark rules.
• Handle comments that look like HTML tags but aren't #381
• Documentation links in workflows crate are broken  #636

[coryan]

If you want known problems: #381, #92