Using @section reorders sections

[klmr]

I’m attempting to document environment variables for a package. My idea was to document them as follows:

#' @section Environment variables:
#' \describe{
#'  \item{\env{VAR1}}{description}
#'  \item{\env{VAR2}}{description}
#' }

Unfortunately this causes ‘roxygen2’ to put this section at the end of the generated .Rd file, out of order (i.e. behind the \details{} section etc.), regardless of where the section was inserted into the Roxygen comment.

R itself isn’t fazed by this: the built-in help page renders the section at the expected position. However, ‘pkgdown’ does not do this, and it puts the section at the very end of the page (following the order of the sections in the .Rd file). Unfortunately this means that I cannot use @section, since the resulting ‘pkgdown’ page is too confusing for users. As a workaround I am using @format instead of @section, but this workaround isn’t ideal, since the “Format” section header is not really accurate, and is also confusing.

MRE:

R/foo.r:

#' Environment variables
#'
#' \pkg{`r .packageName`} can be controlled by the following environment variables:
#'
#' \describe{
#'  \item{\env{VAR1}}{description}
#'  \item{\env{VAR2}}{description}
#' }
#'
#' @details A detailed description.
#' @note The environment variables are read only *once*, during package loading. Subsequent modifications will be ignored until the package is unloaded and reloaded.
#' @evalRd sprintf('\\alias{%s}', c("VAR1", "VAR2"))
#' @name env-vars
NULL

roxygen2::roxygenize()

Expected result

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/foo.r
\name{env-vars}
\alias{env-vars}
\title{Environment variables}
\description{
\pkg{roxytest} can be controlled by the following environment variables:
}
\section{Environment variables}{
\describe{
\item{\env{VAR1}}{description}
\item{\env{VAR2}}{description}
}
}
\details{
A detailed description.
}
\note{
The environment variables are read only \emph{once}, during package loading. Subsequent modifications will be ignored until the package is unloaded and reloaded.
}

\alias{VAR1}
\alias{VAR2}

Actual result

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/foo.r
\name{env-vars}
\alias{env-vars}
\title{Environment variables}
\description{
\pkg{roxytest} can be controlled by the following environment variables:
}
\details{
A detailed description.
}
\note{
The environment variables are read only \emph{once}, during package loading. Subsequent modifications will be ignored until the package is unloaded and reloaded.
}
\section{Environment variables}{

\describe{
\item{\env{VAR1}}{description}
\item{\env{VAR2}}{description}
}
}

\alias{VAR1}
\alias{VAR2}

… since that’s a bit hard to compare, here’s a diff:

--- man/env-vars-actual.Rd	2024-09-23 11:19:04
+++ man/env-vars-expected.Rd	2024-09-23 11:24:38
@@ -7,4 +7,10 @@
 \pkg{roxytest} can be controlled by the following environment variables:
 }
+\section{Environment variables}{
+\describe{
+\item{\env{VAR1}}{description}
+\item{\env{VAR2}}{description}
+}
+}
 \details{
 A detailed description.
@@ -13,12 +19,5 @@
 The environment variables are read only \emph{once}, during package loading. Subsequent modifications will be ignored until the package is unloaded and reloaded.
 }
-\section{Environment variables}{
 
-\describe{
-\item{\env{VAR1}}{description}
-\item{\env{VAR2}}{description}
-}
-}
-
 \alias{VAR1}
 \alias{VAR2}