diff --git a/.ci/Dockerfile b/.ci/Dockerfile index eb59103e1819..26f92a539959 100644 --- a/.ci/Dockerfile +++ b/.ci/Dockerfile @@ -1,8 +1,6 @@ -FROM python:slim +FROM conanio/ci-docs COPY requirements.txt /tmp/ -RUN apt-get update \ - && apt-get install -y enchant-2 git make latexmk texlive-latex-base texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra \ - && pip3 install --requirement /tmp/requirements.txt +RUN pip3 install --requirement /tmp/requirements.txt diff --git a/.ci/test.jenkins b/.ci/test.jenkins index 4511238f130a..8dd4b732697f 100644 --- a/.ci/test.jenkins +++ b/.ci/test.jenkins @@ -3,9 +3,18 @@ node('Linux') { String alphaReleaseBranch = 'release/2.0.0-alpha' boolean publishDocs = env.BRANCH_NAME == alphaReleaseBranch + def targetBranch = env.CHANGE_BRANCH + + // We also have to clone conan sources for the sphinx autodoc extension + def conanBranch = (targetBranch == alphaReleaseBranch) ? 'release/2.0-alpha' : 'develop2' + def conan_repo_url = 'https://github.com/conan-io/conan.git' + echo "Docs target branch: ${targetBranch}" + echo "Conan target branch: ${conanBranch}" stage('Clone sources') { checkout scm + def cloneConan = "git clone --single-branch -b ${conanBranch} --depth 1 ${conan_repo_url} conan_sources" + sh(script: cloneConan) } def image = null @@ -16,17 +25,20 @@ node('Linux') { stage('Test build') { parallel html: { image.inside { - sh 'make html' + // for some reason even adding this to autodoc_mock_imports + // does not work, se we have to install the real dependency + sh(script: 'pip3 install colorama') + sh(script: 'make html') } }, pdf: { image.inside { - sh 'make latex' + sh(script: 'make latex') } }, spelling: { image.inside { - sh 'make spelling' + sh(script: 'make spelling') } }, linkcheck: { diff --git a/conf.py b/conf.py index d5baa7e842c7..42a5eb0c446a 100644 --- a/conf.py +++ b/conf.py @@ -18,11 +18,18 @@ from shutil import copyfile import json +# path to the conan_sources, they must be cloned to the branch +# that we are building the docs for +# if building the docs in local, point this to the local conan_sources + +path_to_conan_sources = './conan_sources' + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('./_themes')) +sys.path.insert(0, os.path.abspath(path_to_conan_sources)) + # -- General configuration ------------------------------------------------ @@ -35,12 +42,21 @@ # ones. extensions = [ 'sphinx.ext.todo', - 'conan', 'sphinxcontrib.spelling', 'sphinx_sitemap', 'notfound.extension', + 'sphinx.ext.autodoc', ] +# autodoc configuration +add_module_names = False +autoclass_content = 'both' +autodoc_mock_imports = ["PyJWT", "requests", "urllib3", "PyYAML", + "patch-ng", "fasteners", "six", "node-semver", "distro", + "pygments", "tqdm", "Jinja2", "MarkupSafe", "Jinja2", + "python-dateutil", "configparse", "patch_ng", "yaml", "semver", "dateutil"] + + # The short X.Y version. version = "2.0-alpha" # The full version, including alpha/beta/rc tags. @@ -104,7 +120,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -exclude_patterns = ['_build', '**/site-packages'] +exclude_patterns = ['_build', '**/site-packages', 'conan_sources/**.rst'] # The reST default role (used for this markup: `text`) to use for all # documents. @@ -134,14 +150,11 @@ todo_include_todos = True -# -- Options for HTML output ---------------------------------------------- -import conan - # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # html_theme = 'sphinx_rtd_theme' html_theme = "conan" -html_theme_path = conan.get_html_theme_path() +html_theme_path = ["_themes"] # Theme options are theme-specific and customize the look and feel of a theme diff --git a/reference.rst b/reference.rst index 20344352f0d5..a2dafe8c6e3c 100644 --- a/reference.rst +++ b/reference.rst @@ -9,3 +9,4 @@ Reference reference/commands reference/python_api + reference/tools diff --git a/reference/python_api.rst b/reference/python_api.rst index f943ce22cfae..a0ea02144f39 100644 --- a/reference/python_api.rst +++ b/reference/python_api.rst @@ -1,2 +1,19 @@ Python API ========== + +.. toctree:: + :maxdepth: 2 + + python_api/ConanAPIV2 + python_api/RemotesAPI + python_api/SearchAPI + python_api/ListAPI + python_api/ProfilesAPI + python_api/InstallAPI + python_api/GraphAPI + python_api/ExportAPI + python_api/RemoveAPI + python_api/ConfigAPI + python_api/NewAPI + python_api/UploadAPI + python_api/DownloadAPI diff --git a/reference/python_api/ConanAPIV2.rst b/reference/python_api/ConanAPIV2.rst new file mode 100644 index 000000000000..dfbaf3cdc4c3 --- /dev/null +++ b/reference/python_api/ConanAPIV2.rst @@ -0,0 +1,17 @@ +Conan API Reference +=================== + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.conan_api + +.. autoclass:: ConanAPIV2 + :members: + + +Read more +--------- + +- Creating Conan custom commands +- ... + diff --git a/reference/python_api/ConfigAPI.rst b/reference/python_api/ConfigAPI.rst new file mode 100644 index 000000000000..beeb425bd4ea --- /dev/null +++ b/reference/python_api/ConfigAPI.rst @@ -0,0 +1,9 @@ +Config API +========== + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.config + +.. autoclass:: ConfigAPI + :members: diff --git a/reference/python_api/DownloadAPI.rst b/reference/python_api/DownloadAPI.rst new file mode 100644 index 000000000000..07d620d802ee --- /dev/null +++ b/reference/python_api/DownloadAPI.rst @@ -0,0 +1,9 @@ +Download API +============ + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.download + +.. autoclass:: DownloadAPI + :members: diff --git a/reference/python_api/ExportAPI.rst b/reference/python_api/ExportAPI.rst new file mode 100644 index 000000000000..6bbb97b3a9bd --- /dev/null +++ b/reference/python_api/ExportAPI.rst @@ -0,0 +1,9 @@ +Export API +========== + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.export + +.. autoclass:: ExportAPI + :members: diff --git a/reference/python_api/GraphAPI.rst b/reference/python_api/GraphAPI.rst new file mode 100644 index 000000000000..425070f59a40 --- /dev/null +++ b/reference/python_api/GraphAPI.rst @@ -0,0 +1,9 @@ +Graph API +========= + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.graph + +.. autoclass:: GraphAPI + :members: diff --git a/reference/python_api/InstallAPI.rst b/reference/python_api/InstallAPI.rst new file mode 100644 index 000000000000..29851e7f07fe --- /dev/null +++ b/reference/python_api/InstallAPI.rst @@ -0,0 +1,9 @@ +Install API +=========== + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.install + +.. autoclass:: InstallAPI + :members: diff --git a/reference/python_api/ListAPI.rst b/reference/python_api/ListAPI.rst new file mode 100644 index 000000000000..5f95f13f897b --- /dev/null +++ b/reference/python_api/ListAPI.rst @@ -0,0 +1,9 @@ +List API +======== + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.list + +.. autoclass:: ListAPI + :members: diff --git a/reference/python_api/NewAPI.rst b/reference/python_api/NewAPI.rst new file mode 100644 index 000000000000..84fec68a7d35 --- /dev/null +++ b/reference/python_api/NewAPI.rst @@ -0,0 +1,9 @@ +New API +======= + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.new + +.. autoclass:: NewAPI + :members: diff --git a/reference/python_api/ProfilesAPI.rst b/reference/python_api/ProfilesAPI.rst new file mode 100644 index 000000000000..7daca6fd0c9d --- /dev/null +++ b/reference/python_api/ProfilesAPI.rst @@ -0,0 +1,9 @@ +Profiles API +============ + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.profiles + +.. autoclass:: ProfilesAPI + :members: diff --git a/reference/python_api/RemotesAPI.rst b/reference/python_api/RemotesAPI.rst new file mode 100644 index 000000000000..7b6c19dbdf23 --- /dev/null +++ b/reference/python_api/RemotesAPI.rst @@ -0,0 +1,9 @@ +Remotes API +=========== + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.remotes + +.. autoclass:: RemotesAPI + :members: \ No newline at end of file diff --git a/reference/python_api/RemoveAPI.rst b/reference/python_api/RemoveAPI.rst new file mode 100644 index 000000000000..1e1e5efd9ba0 --- /dev/null +++ b/reference/python_api/RemoveAPI.rst @@ -0,0 +1,9 @@ +Remove API +========== + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.remove + +.. autoclass:: RemoveAPI + :members: \ No newline at end of file diff --git a/reference/python_api/SearchAPI.rst b/reference/python_api/SearchAPI.rst new file mode 100644 index 000000000000..abf09d99813b --- /dev/null +++ b/reference/python_api/SearchAPI.rst @@ -0,0 +1,9 @@ +Search API +========== + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.search + +.. autoclass:: SearchAPI + :members: \ No newline at end of file diff --git a/reference/python_api/UploadAPI.rst b/reference/python_api/UploadAPI.rst new file mode 100644 index 000000000000..dbd8689e0fc4 --- /dev/null +++ b/reference/python_api/UploadAPI.rst @@ -0,0 +1,9 @@ +Upload API +========== + +.. include:: api_warning.rst + +.. currentmodule:: conan.api.subapi.upload + +.. autoclass:: UploadAPI + :members: diff --git a/reference/python_api/api_warning.rst b/reference/python_api/api_warning.rst new file mode 100644 index 000000000000..537cf799328b --- /dev/null +++ b/reference/python_api/api_warning.rst @@ -0,0 +1,2 @@ +.. warning:: + The Conan API is experimental and subject to breaking changes. diff --git a/reference/tools.rst b/reference/tools.rst new file mode 100644 index 000000000000..4639b37bb6d5 --- /dev/null +++ b/reference/tools.rst @@ -0,0 +1,31 @@ +.. _conan_tools: + +tools +===== + +Tools are all things that can be imported and used in Conan recipes. + +The import path is always like: + +.. code-block:: python + + from conan.tools.cmake import CMakeToolchain, CMakeDeps, CMake + form conan.tools.microsoft import MSBuildToolchain, MSBuildDeps, MSBuild + + +The main guidelines are: + +- Everything that recipes can import belong to ``from conan.tools``. Any other thing is private implementation + and shouldn't be used in recipes. +- Only documented, public (not preceded by ``_``) tools can be used in recipes. + + +Contents: + +.. toctree:: + :maxdepth: 2 + + tools/cmake + tools/env + tools/build + tools/files diff --git a/reference/tools/build.rst b/reference/tools/build.rst new file mode 100644 index 000000000000..dee1fb7cfb14 --- /dev/null +++ b/reference/tools/build.rst @@ -0,0 +1,11 @@ +.. _conan_tools_build: + +conan.tools.build +================= + +conan.tools.build.cross_building() +---------------------------------- + +.. currentmodule:: conan.tools.build.cross_building + +.. autofunction:: cross_building diff --git a/reference/tools/cmake.rst b/reference/tools/cmake.rst new file mode 100644 index 000000000000..5b997786ed40 --- /dev/null +++ b/reference/tools/cmake.rst @@ -0,0 +1,12 @@ +.. _conan_tools_cmake: + +conan.tools.cmake +================= + +.. toctree:: + :maxdepth: 2 + + cmake/cmakedeps + cmake/cmaketoolchain + cmake/cmake + cmake/cmake_layout diff --git a/reference/tools/cmake/cmake.rst b/reference/tools/cmake/cmake.rst new file mode 100644 index 000000000000..d68d4124cf3b --- /dev/null +++ b/reference/tools/cmake/cmake.rst @@ -0,0 +1,12 @@ +.. _conan-cmake-build-helper: + +CMake +----- + +Reference +========= + +.. currentmodule:: conan.tools.cmake.cmake + +.. autoclass:: CMake + :members: diff --git a/reference/tools/cmake/cmake_layout.rst b/reference/tools/cmake/cmake_layout.rst new file mode 100644 index 000000000000..630e84310db8 --- /dev/null +++ b/reference/tools/cmake/cmake_layout.rst @@ -0,0 +1,8 @@ +.. _cmake_layout: + +cmake_layout +------------ + +.. currentmodule:: conan.tools.cmake.layout + +.. autofunction:: cmake_layout diff --git a/reference/tools/cmake/cmakedeps.rst b/reference/tools/cmake/cmakedeps.rst new file mode 100644 index 000000000000..139865324b69 --- /dev/null +++ b/reference/tools/cmake/cmakedeps.rst @@ -0,0 +1,13 @@ +.. _CMakeDeps: + +CMakeDeps +--------- + +Reference +========= + +.. currentmodule:: conan.tools.cmake.cmakedeps.cmakedeps + +.. autoclass:: CMakeDeps + :members: + diff --git a/reference/tools/cmake/cmaketoolchain.rst b/reference/tools/cmake/cmaketoolchain.rst new file mode 100644 index 000000000000..8b3d719da27a --- /dev/null +++ b/reference/tools/cmake/cmaketoolchain.rst @@ -0,0 +1,10 @@ +CMakeToolchain +-------------- + +Reference +========= + +.. currentmodule:: conan.tools.cmake.toolchain.toolchain + +.. autoclass:: CMakeToolchain + :members: diff --git a/reference/tools/env.rst b/reference/tools/env.rst new file mode 100644 index 000000000000..c60e510ae2b7 --- /dev/null +++ b/reference/tools/env.rst @@ -0,0 +1,10 @@ +conan.tools.env +=============== + +.. toctree:: + :maxdepth: 2 + + env/environment + env/envvars + env/virtualbuildenv + env/virtualrunenv diff --git a/reference/tools/env/environment.rst b/reference/tools/env/environment.rst new file mode 100644 index 000000000000..70f5d5479aba --- /dev/null +++ b/reference/tools/env/environment.rst @@ -0,0 +1,9 @@ +.. _conan_tools_env_environment_model: + +Environment +=========== + +.. currentmodule:: conan.tools.env.environment + +.. autoclass:: Environment + :members: diff --git a/reference/tools/env/envvars.rst b/reference/tools/env/envvars.rst new file mode 100644 index 000000000000..012c3ff43999 --- /dev/null +++ b/reference/tools/env/envvars.rst @@ -0,0 +1,7 @@ +EnvVars +======= + +.. currentmodule:: conan.tools.env.environment + +.. autoclass:: EnvVars + :members: diff --git a/reference/tools/env/virtualbuildenv.rst b/reference/tools/env/virtualbuildenv.rst new file mode 100644 index 000000000000..dcf024e1b3ab --- /dev/null +++ b/reference/tools/env/virtualbuildenv.rst @@ -0,0 +1,9 @@ +.. _conan_tools_env_virtualbuildenv: + +VirtualBuildEnv +=============== + +.. currentmodule:: conan.tools.env.virtualbuildenv + +.. autoclass:: VirtualBuildEnv + :members: diff --git a/reference/tools/env/virtualrunenv.rst b/reference/tools/env/virtualrunenv.rst new file mode 100644 index 000000000000..d0fff36f9365 --- /dev/null +++ b/reference/tools/env/virtualrunenv.rst @@ -0,0 +1,9 @@ +.. _conan_tools_env_virtualrunenv: + +VirtualRunEnv +============= + +.. currentmodule:: conan.tools.env.virtualrunenv + +.. autoclass:: VirtualRunEnv + :members: diff --git a/reference/tools/files.rst b/reference/tools/files.rst new file mode 100644 index 000000000000..bbc863c213bf --- /dev/null +++ b/reference/tools/files.rst @@ -0,0 +1,14 @@ +.. _conan_tools_files: + +conan.tools.files +================== + +.. toctree:: + :maxdepth: 2 + + files/basic + files/downloads + files/patches + files/checksum + files/symlinks + files/autopackager diff --git a/reference/tools/files/autopackager.rst b/reference/tools/files/autopackager.rst new file mode 100644 index 000000000000..db4e6fad7e2e --- /dev/null +++ b/reference/tools/files/autopackager.rst @@ -0,0 +1,9 @@ +.. _conan_tools_files_autopackager: + +conan.tools.files.AutoPackager +------------------------------ + +.. currentmodule:: conan.tools.files.packager + +.. autoclass:: AutoPackager + :members: diff --git a/reference/tools/files/basic.rst b/reference/tools/files/basic.rst new file mode 100644 index 000000000000..28246c680dac --- /dev/null +++ b/reference/tools/files/basic.rst @@ -0,0 +1,82 @@ +conan.tools.files basic operations +================================== + + +conan.tools.files.copy() +------------------------ + +.. currentmodule:: conan.tools.files.copy_pattern + +.. autofunction:: copy + + +conan.tools.files.load() +------------------------ + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: load + + +conan.tools.files.save() +------------------------ + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: save + + +conan.tools.files.rename() +-------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: rename + + +conan.tools.files.replace_in_file() +----------------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: replace_in_file + + +conan.tools.files.mkdir() +------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: mkdir + + +conan.tools.files.rmdir() +------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: rmdir + + +conan.tools.files.chdir() +------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: chdir + + +conan.tools.files.unzip() +------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: unzip + + +conan.tools.files.update_conandata() +------------------------------------ + +.. currentmodule:: conan.tools.files.conandata + +.. autofunction:: update_conandata diff --git a/reference/tools/files/checksum.rst b/reference/tools/files/checksum.rst new file mode 100644 index 000000000000..d50cc6e324a7 --- /dev/null +++ b/reference/tools/files/checksum.rst @@ -0,0 +1,26 @@ +conan.tools.files checksums +=========================== + + +conan.tools.files.check_md5() +----------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: check_md5 + + +conan.tools.files.check_sha1() +------------------------------ + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: check_sha1 + + +conan.tools.files.check_sha256() +-------------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: check_sha256 diff --git a/reference/tools/files/downloads.rst b/reference/tools/files/downloads.rst new file mode 100644 index 000000000000..03157700425f --- /dev/null +++ b/reference/tools/files/downloads.rst @@ -0,0 +1,26 @@ +conan.tools.files downloads +=========================== + +conan.tools.files.get() +----------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: get + + +conan.tools.files.ftp_download() +-------------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: ftp_download + + +conan.tools.files.download() +---------------------------- + +.. currentmodule:: conan.tools.files.files + +.. autofunction:: download + diff --git a/reference/tools/files/patches.rst b/reference/tools/files/patches.rst new file mode 100644 index 000000000000..34cbb17dfb26 --- /dev/null +++ b/reference/tools/files/patches.rst @@ -0,0 +1,18 @@ +conan.tools.files patches +========================= + + +conan.tools.files.patch() +------------------------- + +.. currentmodule:: conan.tools.files.patches + +.. autofunction:: patch + + +conan.tools.files.apply_conandata_patches() +------------------------------------------- + +.. currentmodule:: conan.tools.files.patches + +.. autofunction:: apply_conandata_patches diff --git a/reference/tools/files/symlinks.rst b/reference/tools/files/symlinks.rst new file mode 100644 index 000000000000..8dc28dc1b9e9 --- /dev/null +++ b/reference/tools/files/symlinks.rst @@ -0,0 +1,27 @@ +conan.tools.files.symlinks +========================== + + +conan.tools.files.symlinks.absolute_to_relative_symlinks() +---------------------------------------------------------- + +.. currentmodule:: conan.tools.files.symlinks + +.. autofunction:: absolute_to_relative_symlinks + + +conan.tools.files.symlinks.remove_external_symlinks() +---------------------------------------------------------- + +.. currentmodule:: conan.tools.files.symlinks + +.. autofunction:: remove_external_symlinks + + +conan.tools.files.symlinks.remove_broken_symlinks() +---------------------------------------------------------- + +.. currentmodule:: conan.tools.files.symlinks + +.. autofunction:: remove_broken_symlinks +