[Bioc-devel] Excluding internal functions from package manual

[Hervé Pagès]

Hi Burak,

AFAIK 'R CMD build' doesn't generate the PDF of the reference manual but 
'R CMD check' does (it puts the manual in the <pkg>.Rcheck folder). This 
is the manual that we propagate to the package landing pages, and it 
seems that it does indeed include the man pages of the internal 
functionality, that is, the man pages that contain \keyword{internal}.

I investigated this and here is what I found:

- The reference manual can also be generated with 'R CMD Rd2pdf'.

- The Rd2pdf command does NOT include the man pages of the internal 
functionality by default. To include them, one needs to specify the 
--internals option. See 'R CMD Rd2pdf --help'.

- 'R CMD check' actually uses the Rd2pdf command internally to generate 
the manual but for some reason it calls it with the --internals option.

Propagation of the PDF manuals generated by  'R CMD check' was 
implemented a long time ago as part of our build system. I guess the 
reason for doing it that way was because it was the simplest way to go. 
Maybe at the time 'R CMD check' was NOT calling Rd2pdf with the 
--internals option, so everything was fine, and the option was added 
later in more recent versions of R, I don't know (I didn't search R NEWS 
file for that).

I don't know if there's an easy fix besides refactoring slightly the 
build system to include our own Rd2pdf step to generate the PDFs. Maybe 
you want to open an issue at https://github.com/Bioconductor/BBS/issues 
to discuss this further with the BBS maintainers.

Best,

H.

On 13/02/2025 16:48, Burak Ogan Mancarci wrote:
> I maintain gemma.R in bioconductor, a package with quite a few internal
> functions with documentation. In CRAN, functions that are not exported are
> not included in the reference pdf that is generated, however in
> Bioconductor, we seem to have all documented functions included. I have
> been trying to see if there's a difference I can identify but from the
> build logs in bioconductor I see that packages are built using
>
> R CMD build --keep-empty-dirs --no-resave-data --md5 gemma.R
>
> which generates a reference pdf without internal functions.
>
> I am wondering what I am missing here and if there is a way to exclude
> these internal functions from the reference. I have checked a few other
> packages to see how they are handling the issue but I could only see the
> internals being left undocumented entirely
>
> Cheers,
> Ogan
>
> 	[[alternative HTML version deleted]]
>
> _______________________________________________
> Bioc-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel

-- 
Hervé Pagès

Bioconductor Core Team
hpages.on.github using gmail.com