Skip to content

Latest commit

 

History

History
222 lines (148 loc) · 5.68 KB

README.md

File metadata and controls

222 lines (148 loc) · 5.68 KB
Raw

Documentation for conan C/C++ package manager. https://conan.io

Built and served by readthedocs:

Documentation Status

How to build

  • Install python and pip docs.

  • Install the requirements (sphinx):

    $ pip install -r requirements.txt

  • 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 and follows reStructuredText Markup Specification.

Quick reStructuredText 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 texts:

    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...

  • Inline literals with $ to refer to command line commands.

    To create a conan package you can use the ``$ conan create`` command.  You can see a ``$ git clone`` command...

  • Inline literals to refer to code or text inside recipies:

     ``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 identation. Documentation makes an extensive use of bash, python, txt and cmake code-blocks.

.. code-block:: python

    from conans 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.7.8p3@pocoproject/stable
    zlib/1.2.11@conan/stable

.. 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

Identation and line lenght

Make sure all identation is done with spaces. Normally 2 space identation for bulleted lists and 4 space identation for code blocks. In some cases a 3 space identation is needed for reStructuredText specifics like toctrees:

.. 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, extenral links or references.

Do not left any unnecessary or trailing spaces.

Text boxes

Also called Admonitions, they are eyecatching 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 Bintray repositories there are binaries for several mainstream compilers...

.. tip::

    Using profiles is strongly recommended. Learn more about them...

References

Reference are commonly used in the documentation and it is always a good way to highlight texts and give an implicit or explicit importance to something.

Internal reference

Use internal reference when you wnat to refer to a speceific section this documentation. Most of the sections hace reference mark just before its name so you can reference it.

.. _conan_export_pkg_command:

conan export-pkg
================

...

To reference to the conan export-pkg command from another text:

Read more about conan export-pkg commnad :ref:`here<conan_export_pkg_command>`.

External references

Use external references with external url at the bottom of the file like this:

Submit a request to include it in `conan-center`_.
...
...

.. _`conan-center`: https://bintray.com/conan/conan-center

In case you what to use explicit external reference with a link, make sure it is not too long to exceed maximum line lenght, otherwise it should considered to be written as a normal external reference.

If you are just evaluating conan, you can create an account on https://bintray.com