(#4372) [docs] Add table of contents to most documentation pages (#4367)

* Remove trailing spaces - deleted by my IDE * Change to style of heading that mdsnippets understands * Add table-of-contents placeholders, for use by mdsnippets * Add table of contents links - by running mdsnippets (The mdsnippets config file, in the root directory, will be added in a separate PR, as required by repo policies) * Fix 2 typos * Add table of contents.
2025-08-14 02:35:37 +00:00 · 2021-02-02 07:31:49 +00:00
parent c511e97d46
commit 253121597d
6 changed files with 74 additions and 17 deletions
--- a/docs/community_resources.md
+++ b/docs/community_resources.md
@@ -1,6 +1,12 @@
 # Community Resources

-This is a currated list of various bots and helpfull tools that aim to making approaching Conan-Center-Index and contributing easier.
+This is a curated list of various bots and helpful tools that aim to making approaching Conan-Center-Index and contributing easier.
+
+<!-- toc -->
+## Contents
+
+  * [Bots](#bots)
+  * [Tools](#tools)<!-- endToc -->

 ## Bots

--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -1,16 +1,20 @@
 # Contributing to Conan Center Index

-
 The following summarizes the process for contributing to the CCI (Conan Center Index) project.

-Community
---------
+<!-- toc -->
+## Contents
+
+  * [Community](#community)
+  * [Dev-flow & Pull Requests](#dev-flow--pull-requests)
+  * [Issues](#issues)<!-- endToc -->
+
+## Community

 Conan Center Index is an Open Source MIT licensed project.
 Conan Center Index is developed by the Conan maintainers and a great community of contributors.

-Dev-flow & Pull Requests
------------------------
+## Dev-flow & Pull Requests

 CCI follows the ["GitFlow"](https://datasift.github.io/gitflow/IntroducingGitFlow.html) branching model.
 Issues are triaged and categorized mainly by type (package request, bug...) and priority (high, medium...) using GitHub
@@ -29,8 +33,7 @@ To contribute follow the next steps:

 The ``conan-io`` organization maintainers will review and help with the packaging.

-Issues
------
+## Issues

 If you think you found a bug in CCI or in a recipe, open an issue indicating the following:

--- a/docs/faqs.md
+++ b/docs/faqs.md
@@ -1,8 +1,24 @@
 # FAQs

-
 This section gathers the most common questions from the community related to packages and usability of this repository.

+<!-- toc -->
+## Contents
+
+  * [What is the policy on recipe name collisions?](#what-is-the-policy-on-recipe-name-collisions)
+  * [Should reference names use `-` or `_`?](#should-reference-names-use---or-_)
+  * [Why are CMake find/config files and pkg-config files not packaged?](#why-are-cmake-findconfig-files-and-pkg-config-files-not-packaged)
+  * [Should recipes export a recipe's license?](#should-recipes-export-a-recipes-license)
+  * [Why recipes that use build tools (like CMake) that have packages in Conan Center do not use it as a build require by default?](#why-recipes-that-use-build-tools-like-cmake-that-have-packages-in-conan-center-do-not-use-it-as-a-build-require-by-default)
+  * [Are python requires allowed in the `conan-center-index`?](#are-python-requires-allowed-in-the-conan-center-index)
+  * [What version should packages use for libraries without official releases?](#what-version-should-packages-use-for-libraries-without-official-releases)
+  * [Is the Jenkins orchestration library publicly available?](#is-the-jenkins-orchestration-library-publicly-available)
+  * [Why not x86 binaries?](#why-not-x86-binaries)
+      * [But if there are no packages available, what will the x86 validation look like?](#but-if-there-are-no-packages-available-what-will-the-x86-validation-look-like)
+  * [Why PDB files are not allowed?](#why-pdb-files-are-not-allowed)
+      * [Why is there no option for PDB, as there is for fPIC?](#why-is-there-no-option-for-pdb-as-there-is-for-fpic)
+  * [Why _installer_ packages remove some settings from their package ID?](#why-_installer_-packages-remove-some-settings-from-their-package-id)<!-- endToc -->
+
 ## What is the policy on recipe name collisions?

 Packages generated by the build service and uploaded to Conan Center follow the structure of `<name>/<version>` for the reference. Although the ecosystem of C/C++ open-source libraries is not as big as in other languages there is still a risk of having a name collision for the names of the package.
--- a/docs/how_to_add_packages.md
+++ b/docs/how_to_add_packages.md
@@ -1,5 +1,20 @@
 # Adding Packages to ConanCenter

+<!-- toc -->
+## Contents
+
+  * [Join the Early Access Program](#join-the-early-access-program)
+  * [More Information about Recipes](#more-information-about-recipes)
+    * [Before start](#before-start)
+    * [The recipe folder](#the-recipe-folder)
+    * [The version folder/s](#the-version-folders)
+    * [The conanfile.py and `test_package` folder](#the-conanfilepy-and-test_package-folder)
+    * [The `conandata.yml`](#the-conandatayml)
+    * [How to provide a good recipe](#how-to-provide-a-good-recipe)
+    * [Test the recipe locally](#test-the-recipe-locally)
+    * [Updating conan hooks on your machine](#updating-conan-hooks-on-your-machine)
+    * [Debugging failed builds](#debugging-failed-builds)<!-- endToc -->
+
 ## Join the Early Access Program

 The first step in adding packages to ConanCenter is requesting access to the Early Access Program. To enroll in EAP, please send an email to info@conan.io with the subject [EAP access] or add a comment on this GitHub [issue](https://github.com/conan-io/conan-center-index/issues/4). The EAP was designed to onboard authors to the new process.
--- a/docs/reviewing.md
+++ b/docs/reviewing.md
@@ -2,6 +2,13 @@

 The following policies are preferred during the review, but not mandatory:

+<!-- toc -->
+## Contents
+
+  * [Trailing white-spaces](#trailing-white-spaces)
+  * [Quotes](#quotes)
+  * [Order of methods and attributes](#order-of-methods-and-attributes)<!-- endToc -->
+
 ## Trailing white-spaces

 Avoid trailing white-space characters, if possible
--- a/docs/supported_platforms_and_configurations.md
+++ b/docs/supported_platforms_and_configurations.md
@@ -1,12 +1,22 @@
 # Supported platforms and configurations

-The pipeline iterates a fixed list of profiles for every Conan reference, 
-it computes the packageID for each profile and discard duplicates. Then it 
-builds the packages for the remaining profiles and upload them to 
+<!-- toc -->
+## Contents
+
+  * [Introduction](#introduction)
+  * [Windows](#windows)
+  * [Linux](#linux)
+  * [MacOS](#macos)<!-- endToc -->
+
+## Introduction
+
+The pipeline iterates a fixed list of profiles for every Conan reference,
+it computes the packageID for each profile and discard duplicates. Then it
+builds the packages for the remaining profiles and upload them to
 [JFrog ConanCenter](https://conan.io/center/) once the pull-request is merged.

-Because duplicated packageIDs are discarded, the pipeline iterates the 
-profiles always in the same order and the profiles selected to build when 
+Because duplicated packageIDs are discarded, the pipeline iterates the
+profiles always in the same order and the profiles selected to build when
 there is a duplicate follow some rules:

 * Static linkage (option `shared=False`) is preferred over dynamic linking.
@@ -15,9 +25,9 @@ there is a duplicate follow some rules:
 * Older compiler versions are considered first.
 * In Linux, GCC is iterated before Clang.

-Currently, given the following supported platforms and configurations we 
-are generating **136 different binary packages for a C++ library** 
-and **88 for a C library**. 
+Currently, given the following supported platforms and configurations we
+are generating **136 different binary packages for a C++ library**
+and **88 for a C library**.


 ## Windows