Find all adoc files included in a document

[ghost]

Within the TRD repo, current main, if you run list-srcfiles, you get this:

> daps -d Kubernetes/RA/DC-TRD-Kubernetes-ri-rancher-k3s-sles list-srcfiles --xmlonly

/path/to/trd/Kubernetes/RA/adoc/./SA-Appendix.adoc
/path/to/trd/Kubernetes/RA/adoc/./SA-Glossary.adoc
/path/to/trd/Kubernetes/RA/adoc/./SA-References.adoc
/path/to/trd/Kubernetes/RA/adoc/./SA-Summary.adoc
/path/to/trd/Kubernetes/RA/adoc/./SA_vars.adoc
/path/to/trd/Kubernetes/RA/adoc/./common_docinfo_vars.adoc
/path/to/trd/Kubernetes/RA/adoc/./i/SA.adoc
/path/to/trd/Kubernetes/RA/adoc/./iv/SA.adoc
/path/to/trd/Kubernetes/RA/adoc/./v/SA.adoc
/path/to/trd/Kubernetes/RA/adoc/./vi/SA.adoc
/path/to/trd/Kubernetes/RA/adoc/SA.adoc

DAPS does appear to be picking up top-level, unconditional includes, but I think it does not seem to pick up conditional includes and includes nested further down, e.g. /path/to/trd/Kubernetes/RA/adoc/./i/SA.adoc has this include for adoc/i/SA-Rancher.adoc which is not listed:

ifdef::focusRancher[]
include::./SA-{an_Rancher}.adoc[]
endif::focusRancher[]

If I understand correctly, the use case for this would be both (1) running this via CI to alert authors about documents affected by a change and (2) in-document usage, much like the parameters that are shown within the appendix (#573).

[cc @tlssuse @bwgartner]

[ghost]

Frank told me that from the normal AsciiDoctor command line tool, this is impossible to do, unless you actually write an own AsciiDoc parser. However, based on this forum thread, getting the list of files is possible via the Ruby API of AsciiDoctor.

I am a Ruby illiterate, but it's possible to try this out with the irb Ruby shell:

bash> irb

irb> require 'asciidoctor'
=> true

irb> doc = Asciidoctor.load_file '/path/to/trd-repo/Kubernetes/RA/adoc/SA.adoc', safe: :safe , attributes: ['env-daps=1','References=1','Glossary=1','Appendix=1','LN=1','GFDL=1','RA=1','BP=1','iRMT=1','iSLES=1','iSLEMicro=1','iSUMa=1','iK3s=1','iRKE1=1','iRKE2=1','iRancher=1','BPBV=1','Requirements=1','ArchOv=1','CompMod=1','SWComp=1','HWComp=1','Deployment=1','HWDepCfg=1','SWDepCfg=1','DepConsiderations=1','RC=1','focusK3s=1','layerSLEMicro=1','FLVR=1','PoC=1','PoC=1','Production=1','Scaling=1','FCTR=1','Automation=1','Availability=1','Security=1','Integrity=1','iIHV=1','IHV-Supermicro=1','IHV-Supermicro-SuperServer=1']

=>[...a lot of output here, all snipped...]

irb> doc.catalog[:includes]
=> {"common_docinfo_vars"=>true, "SA_vars"=>true, "CSP/SA_vars"=>true, "IHV/SA_vars"=>true, "ISV/SA_vars"=>true, "SUSE/SA_vars"=>true, "SUSE/Rancher/SA_vars"=>true, "SUSE/RKE1/SA_vars"=>true, "SUSE/RKE2/SA_vars"=>true, "SUSE/K3s/SA_vars"=>true, "SUSE/RMT/SA_vars"=>true, "SUSE/SLE-Micro/SA_vars"=>true, "SUSE/SLES/SA_vars"=>true, "SUSE/SUMa/SA_vars"=>true, "i/SA"=>true, "i/SA-Kubernetes"=>true, "ii/SA"=>true, "ii/SA-RA-BPBV"=>true, "ii/SA-RA-BPBV-K3s"=>true, "IHV/Supermicro/SuperServer/SA-RA-BPBV"=>true, "iv/SA"=>true, "iv/SA-RA-ArchOv"=>true, "iv/SA-RA-ArchOv-K3s"=>true, "v/SA"=>true, "v/SA-RA-CompMod"=>true, "v/SA-RA-CompMod-K3s"=>true, "SUSE/K3s/SA"=>true, "SUSE/SLE-Micro/SA"=>true, "IHV/Supermicro/SuperServer/SA-RA-CompMod"=>true, "IHV/Supermicro/SuperServer/Supermicro_vars"=>true, "vi/SA"=>true, "vi/SA-RA-Deployment"=>true, "vi/SA-RA-Deployment-Hardware"=>true, "IHV/Supermicro/SuperServer/SYS-120C-TN10R"=>true, "IHV/Supermicro/SuperServer/SYS-620C-TN12R"=>true, "vi/SA-RA-Deployment-OS"=>true, "vi/SA-RA-Deployment-OS-prep"=>true, "vi/SA-RA-Deployment-K3s"=>true, "vi/SA-RA-Deployment-Workload"=>true, "SA-Summary"=>true, "SA-References"=>true, "SA-Glossary"=>true, "SA-Appendix"=>true, "SUSE/common_trd_legal_notice"=>true, "SUSE/common_gfdl1.2_i"=>true}

Besides the file extensions missing, that looks about right.

The big question here is whether that call can be integrated into DAPS. But maybe, Bryan/Terry, it helps you for the moment anyway even as it is not integrated.

(AsciiDoctor API docs: https://docs.asciidoctor.org/asciidoctor/latest/api/options/)

[bwgartner]

Stefan, this is a great find and quite usable! I replicated your example run, have tried another one as well, so will try to generate a matrix of RA include files across various documents to review.

[ghost]

Relevant for doc-suse-com/site#53.

[fsundermeyer]

I have to admit that I do not have the slightest clue of how to utilize Stefan's findings with the irb shell in DAPS (help is welcome).

What I have done with 7506323 is to make sure that DAPS finds all include files plus the docinfo file. There is still some shortcomings:

• adoc profiling is not taken into account (this would rather require the irb appraoch). So all includes are liste unconditionally
• using entities/variables in includes will not work with my approach. All includes that use variables (like in include::./SA-{an_Rancher}.adoc[]) will silently be ignored @bwgartner : would it be possible to refrain from using variables that way?
• not sure if that would be possible, but xi:includes from the docinfo files would not be taken into account

BTW: "Profiling" for images works (the file list will only show images, that are used in the resulting document, including images specified in the docinfo file). This is because images are extracted from the resulting XML.