From aabd63d7f4f2d5594c5f4aa95f5bd217c0f8b077 Mon Sep 17 00:00:00 2001 From: Florian Festi Date: Fri, 6 Oct 2023 11:56:26 +0200 Subject: [PATCH] Add docs/README.md giving a rough outline of the different doc parts. Related: #2259 --- docs/CMakeLists.txt | 1 + docs/README.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 docs/README.md diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index 0c499b64ac..780e1c140d 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -16,6 +16,7 @@ endif() install(DIRECTORY ${doxsrc}/html/ DESTINATION ${CMAKE_INSTALL_DOCDIR}/API) install(FILES + README.md manual/arch_dependencies.md manual/autosetup.md manual/boolean_dependencies.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..896c50026a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,30 @@ +RPM Documentation +================= + +There are multiple pieces of documentation that are processed and used differently. + +RPM.org +------- + +The [rpm.org web page](https://rpm.org/) is created from its own [GitHub repository](https://github.com/rpm-software-management/rpm-web). + +Man Pages +--------- + +The man pages in *man/* are Markdown documents. They are rendered to the man page format during build. These pre-rendered pages are also shipped with the (release) tarball. That way building rpm from the tarball does not require the *pandoc* as long as the man pages are unchanged. + +The man pages are also rendered to HTML together with the Reference Manual (see below). + +API Reference +------------- + +The API reference is rendered with *Doxygen*. The content is almost exclusively created from the RPM sources and the doc strings there in. The rendered HTML is shipped with the release tarball to be able to build RPM from that without *Doxygen*. + +Reference Manual +---------------- + +The reference manual in the *manual/* dir is an GitHub Pages site. It is rendered automatically when pushed into the *master* branch in the GitHub repository. It is available online on [its own URL](https://rpm-software-management.github.io/rpm/manual/) but is intended to be used as part of the [RPM.org website](https://rpm.org/) were it is linked from the [Documentation page](https://rpm.org/documentation.html) + +The Reference Manual is currently not shipped in rendered form in the tarball. + +To render it locally one can follow [this article](https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyll) and render it with *Jekyll* with the use of the *github-pages* gem.