[libc++][doc] Use sphinx variables to make updating the docs version easier

[tstellar]

Add some more changes.

[Mordante]

libcxx/docs/ReleaseNotes.rst

13–16

Would it be possible to automatically remove this block, including the .. warning:: at line 11, when the version is a release?

libcxx/docs/conf.py

45–46

The current output "libc++ 14.0.0git documentation" looks weird.

45–46

I expect for a release I'd have to remove + 'git', but doing so results in errors when building the documentation.

make[3]: *** [projects/libcxx/docs/CMakeFiles/docs-libcxx-html.dir/build.make:58: projects/libcxx/docs/CMakeFiles/docs-libcxx-html] Error 2
make[2]: *** [CMakeFiles/Makefile2:25091: projects/libcxx/docs/CMakeFiles/docs-libcxx-html.dir/all] Error 2
make[1]: *** [CMakeFiles/Makefile2:25098: projects/libcxx/docs/CMakeFiles/docs-libcxx-html.dir/rule] Error 2
make: *** [Makefile:7544: docs-libcxx-html] Error 2

Do I misunderstand the intention or is there a real error?

[tstellar]

Thanks for the feedback. Here is an updated version of the patch with
some of your suggestions.

[tstellar]

libcxx/docs/conf.py

45–46

I decided to drop the 'git' suffix in order to simplify the config. I can add it back (with the '-' in front of it) if you think it helps remind readers that it is a pre-release.

[tstellar]

I rewrote this patch to take variables directly from cmake, so we don't need to hard-code
them in the libcxx config file. With this change, Makefile.sphinx will stop working, so
I've deleted it, but I can add it back and fix it if people are still using it.

I plan to update the other sub-projects to take advantage of this new approach, once we're done
with libcxx.

[tstellar]

libcxx/docs/conf.py

45–46

The version string is 14.0.0git again now that I'm using PACKAGE_VERSION directly from CMake. This form of the version string is used in other places, so I would lean towards just keeping it as is.

[ldionne]

The intent of the change looks good to me, i.e. using variables to set the version number & al.

However, I checked out this patch and built the documentation, and it doesn't show "In Progress" anymore, nor does it have any mention of being the libc++ 14.0.0 incoming release. Is that intended? IMO, it was useful to have that visual marker about notes being in-progress release notes for an upcoming release.

If that's not intended, then I assume this is most likely caused by a difference in how we run our builds. What I'm using is:

$ git clone https://github.com/llvm/llvm-project.git
$ cd llvm-project
$ mkdir build
$ cmake -G Ninja -S runtimes -B build -DLLVM_ENABLE_RUNTIMES="libcxx;libcxxabi;libunwind" -DLLVM_ENABLE_SPHINX=ON
$ ninja -C build docs-libcxx-html

libcxx/docs/Makefile.sphinx

1

This is fine - I don't think there's any desire to keep this around, at least not from my side.

[tstellar]

In D111926#3071070, @ldionne wrote:

The intent of the change looks good to me, i.e. using variables to set the version number & al.

However, I checked out this patch and built the documentation, and it doesn't show "In Progress" anymore, nor does it have any mention of being the libc++ 14.0.0 incoming release. Is that intended? IMO, it was useful to have that visual marker about notes being in-progress release notes for an upcoming release.

It's not intended. I will try to reproduce with your build configuration.

[tstellar]

In D111926#3071076, @tstellar wrote:

In D111926#3071070, @ldionne wrote:

The intent of the change looks good to me, i.e. using variables to set the version number & al.

However, I checked out this patch and built the documentation, and it doesn't show "In Progress" anymore, nor does it have any mention of being the libc++ 14.0.0 incoming release. Is that intended? IMO, it was useful to have that visual marker about notes being in-progress release notes for an upcoming release.

It's not intended. I will try to reproduce with your build configuration.

It looks like the runtime builds don't have access to the LLVM_VERSION* cmake variables, which is why the version information is missing. I think I'll try to convert some of the non-runtime sub-projects first and then revisit libcxx once I'm done with those.

[ldionne]

In D111926#3071164, @tstellar wrote:

In D111926#3071076, @tstellar wrote:

In D111926#3071070, @ldionne wrote:

The intent of the change looks good to me, i.e. using variables to set the version number & al.

However, I checked out this patch and built the documentation, and it doesn't show "In Progress" anymore, nor does it have any mention of being the libc++ 14.0.0 incoming release. Is that intended? IMO, it was useful to have that visual marker about notes being in-progress release notes for an upcoming release.

It's not intended. I will try to reproduce with your build configuration.

It looks like the runtime builds don't have access to the LLVM_VERSION* cmake variables, which is why the version information is missing. I think I'll try to convert some of the non-runtime sub-projects first and then revisit libcxx once I'm done with those.

Alright, sounds good to me. Sorry our build system migration is clashing with this effort, but at least it's good that we're aware of it.

[Mordante]

I really like the direction this patch is taking. I want to give it another testrun after the runtime builds are fixed.
(I still use a non-runtime build.)

libcxx/docs/ReleaseNotes.rst

3

Please resize line 1 and 3 to match line 2.

libcxx/docs/conf.py

45–46

Since we use 14.0.0git in other places I agree we should be consistent and do the same in the documentation.

[Mordante]

@tstellar What's the status of this patch? It would be great to have this in the LLVM14 release.

[tstellar]

@Mordante I haven't had time to look at fixing the runtime builds yet.

libcxx/docs/Makefile.sphinx

-# Makefile for Sphinx documentation
-#
-# FIXME: This hack is only in place to allow the libcxx.llvm.org/docs builder
-# to work with libcxx. This should be removed when that builder supports
-# out-of-tree builds.
-
-# You can set these variables from the command line.
-SPHINXOPTS    = -n -W -v
-SPHINXBUILD   = sphinx-build
-PAPER         =
-BUILDDIR      = _build
-
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-# the i18n builder cannot share the environment and doctrees with the others
-I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
-
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext default
-
-default: html
-
-help:
-  @echo "Please use \`make <target>' where <target> is one of"
-  @echo "  html       to make standalone HTML files"
-
-clean:
-  -rm -rf $(BUILDDIR)/*
-
-html:
-  $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-  @echo
-  @# FIXME: Remove this `cp` once HTML->Sphinx transition is completed.
-  @# Kind of a hack, but HTML-formatted docs are on the way out anyway.
-  @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-

libcxx/docs/ReleaseNotes.rst

-=========================================
-Libc++ 14.0.0 (In-Progress) Release Notes
-=========================================
+==================================================
+Libc++ |version| |ReleaseNotesTitle|
+==================================================
 
 .. contents::
    :local:
    :depth: 2
 
 Written by the `Libc++ Team <https://libcxx.llvm.org>`_
 
-.. warning::
+.. only:: PreRelease
 
-   These are in-progress notes for the upcoming libc++ 14 release.
+  .. warning::
+     These are in-progress notes for the upcoming libc++ |version| release.
      Release notes for previous releases can be found on
      `the Download Page <https://releases.llvm.org/download.html>`_.
 
 Introduction
 ============
 
 This document contains the release notes for the libc++ C++ Standard Library,
-part of the LLVM Compiler Infrastructure, release 14.0.0. Here we describe the
+part of the LLVM Compiler Infrastructure, release |version|. Here we describe the
 status of libc++ in some detail, including major improvements from the previous
 release and new feature work. For the general LLVM release notes, see `the LLVM
 documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
 be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.
 
 For more information about libc++, please see the `Libc++ Web Site
 <https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.
 
 Note that if you are reading this file from a Git checkout or the
 main Libc++ web page, this document applies to the *next* release, not
 the current one. To see the release notes for a specific release, please
 see the `releases page <https://llvm.org/releases/>`_.
 
-What's New in Libc++ 14.0.0?
-============================
+What's New in Libc++ |version|?
+===============================
 
 New Features
 ------------
 
 - There's initial support for the C++20 header ``<format>``. The implementation
   is incomplete. Some functions are known to be inefficient; both in memory
   usage and performance. The implementation is considered experimental and isn't
   considered ABI stable.

libcxx/docs/conf.py

 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
 project = u'libc++'
 copyright = u'2011-%d, LLVM Project' % date.today().year
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
-version = '14.0'
-# The full version, including alpha/beta/rc tags.
-release = '14.0'
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
 today_fmt = '%Y-%m-%d'

 show_authors = True
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'friendly'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
+in_progress_title = "(In-Progress) " if tags.has("PreRelease") else ""
+
+rst_epilog = f"""
+.. |ReleaseNotesTitle| replace:: {in_progress_title} Release Notes
+"""
 
 # -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 html_theme = 'haiku'
 
 # Theme options are theme-specific and customize the look and feel of a theme

llvm/cmake/modules/AddSphinxTarget.cmake

function (add_sphinx_target builder project)
   else()
     set(SPHINX_WARNINGS_AS_ERRORS_FLAG "")
   endif()
 
   if (NOT ARG_SOURCE_DIR)
     set(ARG_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}")
   endif()
 
+  if ("${LLVM_VERSION_SUFFIX}" STREQUAL "git")
+    set(PreReleaseTag "-tPreRelease")
+  endif()
+
   add_custom_target(${SPHINX_TARGET_NAME}
                     COMMAND ${CMAKE_COMMAND} -E env ${ARG_ENV_VARS}
                             ${SPHINX_EXECUTABLE}
                             -b ${builder}
                             -d "${SPHINX_DOC_TREE_DIR}"
                             -q # Quiet: no output other than errors and warnings.
                             -t builder-${builder} # tag for builder
+                            -D version=${LLVM_VERSION_MAJOR}
+                            -D release=${PACKAGE_VERSION}
+                            ${PreReleaseTag}
                             ${SPHINX_WARNINGS_AS_ERRORS_FLAG} # Treat warnings as errors if requested
                             "${ARG_SOURCE_DIR}" # Source
                             "${SPHINX_BUILD_DIR}" # Output
                     COMMENT
                     "Generating ${builder} Sphinx documentation for ${project} into \"${SPHINX_BUILD_DIR}\"")
 
   # When "clean" target is run, remove the Sphinx build directory
   set_property(DIRECTORY APPEND PROPERTY