https://github.com/conan-io/docs
conan.io reStructuredText documentation
https://github.com/conan-io/docs
conan conan-documentation documentation restructuredtext
Last synced: 10 months ago
JSON representation
conan.io reStructuredText documentation
- Host: GitHub
- URL: https://github.com/conan-io/docs
- Owner: conan-io
- License: mit
- Created: 2015-12-01T11:42:37.000Z (over 10 years ago)
- Default Branch: develop2
- Last Pushed: 2025-04-29T12:54:43.000Z (11 months ago)
- Last Synced: 2025-05-13T09:07:47.588Z (10 months ago)
- Topics: conan, conan-documentation, documentation, restructuredtext
- Language: NASL
- Homepage: http://docs.conan.io
- Size: 286 MB
- Stars: 113
- Watchers: 18
- Forks: 370
- Open Issues: 371
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.rst
- License: LICENSE
Awesome Lists containing this project
README
Documentation for Conan C/C++ package manager: https://conan.io
How to build
============
- Install prerequisites:
- [graphviz](https://graphviz.org/download)
- [enchant](https://pyenchant.github.io/pyenchant/install.html)
- Install python and [pip docs](https://pip.pypa.io/en/stable/installing/).
- Install the requirements (sphinx):
`$ pip install -r requirements.txt`
- Point to the Conan source code folder (``git clone https://github.com/conan-io/conan && cd conan && git checkout develop2``)
- Windows:
`$ set PYTHONPATH=;%PYTHONPATH%`
- Linux:
`$ export PYTHONPATH=:$PYTHONPATH`
- Build the documentation:
`$ make html`
How to read the built docs
==========================
Open a browser and select the *_build/html/index.html* file.
Example:
`$ firefox _build/html/index.html`
How to contribute
=================
To make any contribution to Conan documentation fork this repository and open a Pull Request.
Style Guidelines
----------------
This guidelines are just general good practices for the formatting and structure of the whole documentation and do not pretend to be a
stopper for any helpful contribution. Any contribution that may include relevant information for Conan users will always be welcomed.
Conan documentation is written in [reStructuredText](http://docutils.sourceforge.net/rst.html) and
follows [reStructuredText Markup Specification](http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html).
[Quick reStructuredText](http://docutils.sourceforge.net/docs/user/rst/quickref.html) is also used for reference.
Any detail not covered by this guidelines will follow the aforementioned rules.
### Section titles
Use section titles in this level of importance:
```
Section Title
=============
Section Title
-------------
Section Title
+++++++++++++
Section Title
^^^^^^^^^^^^^
```
### Text emphasis/highlighting
- **Bold text** to highlight important text:
```
Note the simple scenario of a **header-only** library. Such package...
```
- *Italics* to refer to file names, directory names and paths.
```
If you have a look to the *test_package* folder, you will realize that the *example.cpp* and the *CMakeLists.txt* files don't have
anything special. The *test_package/conanfile.py* file is...
```
- ``Command inline literals`` to refer to command line, both full commands and command line arguments, or any extract of a full command.
```
To create a conan package you can use :command:`conan create`. You can see a :command:`git clone` command... You may call it with the :command:`--keep-source` option to avoid deleting and fetching the source.
```
- ``Inline literals`` to refer to code or text inside recipes:
```
``package()`` -> conanfile.py method
``cmake`` -> generator in conanfile.txt
``settings`` -> variable inside a ConanFile class in conanfile.py
```
Like this:
```
Note that the ``build_id()`` method uses the ``self.info_build`` object to alter the build hash.
```
- Other names like CMake, Autotools, Conan, Visual Studio should not be emphasized, just use a capital letter or follow the convention (like
first and second capitalized letters for CMake).
### code-blocks
Use code-blocks for code snippets or command line actions and follow the specific language
indentation. Documentation makes an extensive use of bash, python, txt and cmake code-blocks.
```
.. code-block:: python
from conan import ConanFile
class EigenConan(ConanFile)
name = "eigen"
version = "3.3.4"
def source():
tools.get("https://some_url.org")
...
```
```
.. code-block:: text
[requires]
poco/1.9.4
zlib/1.2.11
```
```
.. code-block:: bash
:emphasize-lines: 3
$ conan source . --source-folder src
$ conan install --install-folder build_x86 -s arch=x86
$ conan build . --build-folder build_x86 --source-folder src
$ conan export-pkg . Hello/0.1@user/stable --build-folder build_x86
```
### Indentation and line length
Make sure all indentation is done with spaces. Normally 2 space indentation for bulleted lists and 4 space indentation for code blocks. In some
cases a 3 space indentation is needed for reStructuredText specifics like toc-trees:
```
.. toctree::
:maxdepth: 2
creating_packages/getting_started
creating_packages/package_repo
```
The **maximum line length for documentation is 140 characters** except for lines inside code-blocks, external links or references.
Do not leave any unnecessary or trailing spaces.
### Text boxes
Also called **Admonitions**, they are eye-catching texts with a clear purpose like warnings, tips or important content.
Use them in the following importance order:
1. caution
2. attention
3. warning
4. important
5. note
6. tip
```
.. warning::
In the ConanCenter repository there are binaries for several mainstream compilers...
```
```
.. tip::
Using profiles is strongly recommended. Learn more about them...
```
### References
References are commonly used in the documentation and it's always a good way to highlight texts and give an implicit or explicit importance
to something.
#### Internal reference
Use an internal reference when you want to refer to a specific section in this documentation. Most of the sections have a reference mark
just before their names so you can reference it.
```
.. _conan_export_pkg_command:
conan export-pkg
================
...
```
To add a reference to the `conan export-pkg` command from another text:
```
Read more about the :ref:`conan export-pkg` command.
Or reference the :ref:`conan_export_pkg_command` directly.
```
#### External references
Use external references with external URL at the bottom of the file like this:
```
Submit a pull request to include it in `conan-center-index`_.
...
...
.. _`conan-center`: https://center2.conan.io
```
In case you want to use explicit external references with a link, make sure it doesn't exceed the maximum line length, otherwise it
should considered to be written as a normal external reference.