Fix extractManuals

[jwokaty]

Allow extractManuals to work on software and experiment tarballs while fixing problems related to the two types of data annotation tarballs. Some data annotation packages are built by the BBS while others are produced outside of it. Currently, reference manuals may be produced twice for the manuals built by the BBS because it is first produced by make-OUTGOING.py in the BBS then later during the propagation step, extractManuals is called. Sometimes extractManuals can fail to create the reference manual resulting in no manual being available.

More background: Bioconductor/BBS#444

Close #18

[jwokaty]

@hpages Could you review when you have time It isn't great because I realized R CMD Rd2pdf will complain if man exists without .Rd files so I decided to create it inside the package directory then move it into man. I also switched to system2 because I thought it was supposed to be better but I can't find any references for belief. I diverted all the output so we will only know when something fails (but it will be easier to see!).

[jwokaty]

This should be merged before Bioconductor/BBS#438, which removes functionality to extract manuals created during the build process that contain internal functions.

[jwokaty]

Hi @vjcitn @lshep Could I ask one of you to review the changes here? I'm also open to suggestions to improve it.

This PR expands extractManuals

• for use with software and data experiment packages (so that manuals will not include internal functions as their current manuals do now)
• to generate a manual page for packages that don't have manuals
• to generate HTML manuals

For testing, I made CRAN-style repo and curled the sources from the Bioconductor website to src/contrib. The resulting structure looks like

tree -L 5 PACKAGES
PACKAGES
└── 3.21
    └── data
        └── annotation
            └── src
                └── contrib
                    ├── aasomething_1.3.5.tar.gz     # a fake package to make sure we fail
                    ├── AHCytoBands_0.99.1.tar.gz  # package without a manual
                    ├── AHEnsDbs_1.7.0.tar.gz
                    ├── alternativeSplicingEvents.hg38_1.1.0.tar.gz # package with a manual
                    └── TENET.AnnotationHub_1.0.0.tar.gz

The result of running extractManuals should produce a manuals directory at the same level of src like

tree -L 6 PACKAGES/3.21/data/annotation/manuals/
PACKAGES/3.21/data/annotation/manuals/
├── AHCytoBands
│   └── man
│       ├── AHCytoBands.html
│       └── AHCytoBands.pdf     # for "no manual" packages, their manuals are of DESCRIPTION file info
├── AHEnsDbs
│   └── man
│       ├── AHEnsDbs.html
│       └── AHEnsDbs.pdf
├── alternativeSplicingEvents.hg38
│   └── man
│       ├── alternativeSplicingEvents.hg38.html
│       └── alternativeSplicingEvents.hg38.pdf
└── TENET.AnnotationHub
    └── man
        ├── TENET.AnnotationHub.html
        └── TENET.AnnotationHub.pdf

[vjcitn]

I think extractManuals should be a tested function. I don't know how hard it would be to set up "mock" repository with some resources that can go in inst to test this. The roxygen documentation for the parameters should be present for this function IMHO. @LiNk-NY may have further comments on the feasibility of this.

[jwokaty]

@vjcitn I've added tests with a mock repo along inst to check that extractManuals

• works for software, annotations, and experiments
• creates manuals for packages that don't have documentation
• creates both html and pdf manuals

I updated the documentation for the function, but the package doesn't use roxygen.