Add support for autodoc in develop2 (#2492)

czoido · web-flow · commit c2b684fe769f · 2022-04-22T11:40:19.000+02:00
* use conan themen

* add autodocs

* update ci

* test autodoc

* wip

* wip

* install colorama

* mock

* wip

* add comment

* use conanio/ci-docs

* add api structure

* wip

* add experimental note
diff --git 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
@@ -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
@@ -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
@@ -9,3 +9,4 @@ Reference
 
    reference/commands
    reference/python_api
+   reference/tools
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -0,0 +1,9 @@
+Remotes API
+===========
+
+.. include:: api_warning.rst
+
+.. currentmodule:: conan.api.subapi.remotes
+
+.. autoclass:: RemotesAPI
+    :members:
diff --git a/reference/python_api/RemoveAPI.rst b/reference/python_api/RemoveAPI.rst
@@ -0,0 +1,9 @@
+Remove API
+==========
+
+.. include:: api_warning.rst
+
+.. currentmodule:: conan.api.subapi.remove
+
+.. autoclass:: RemoveAPI
+    :members:
diff --git a/reference/python_api/SearchAPI.rst b/reference/python_api/SearchAPI.rst
@@ -0,0 +1,9 @@
+Search API
+==========
+
+.. include:: api_warning.rst
+
+.. currentmodule:: conan.api.subapi.search
+
+.. autoclass:: SearchAPI
+    :members:
diff --git a/reference/python_api/UploadAPI.rst 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
diff --git a/reference/tools/env/environment.rst b/reference/tools/env/environment.rst
diff --git a/reference/tools/env/envvars.rst b/reference/tools/env/envvars.rst
diff --git a/reference/tools/env/virtualbuildenv.rst b/reference/tools/env/virtualbuildenv.rst
diff --git a/reference/tools/env/virtualrunenv.rst b/reference/tools/env/virtualrunenv.rst
diff --git a/reference/tools/files.rst b/reference/tools/files.rst
diff --git a/reference/tools/files/autopackager.rst b/reference/tools/files/autopackager.rst
diff --git a/reference/tools/files/basic.rst b/reference/tools/files/basic.rst
diff --git a/reference/tools/files/checksum.rst b/reference/tools/files/checksum.rst
diff --git a/reference/tools/files/downloads.rst b/reference/tools/files/downloads.rst
diff --git a/reference/tools/files/patches.rst b/reference/tools/files/patches.rst
diff --git a/reference/tools/files/symlinks.rst b/reference/tools/files/symlinks.rst

Original file line number	Diff line number	Diff line change
`@@ -9,3 +9,4 @@ Reference`
`9`	`9`
`10`	`10`	`reference/commands`
`11`	`11`	`reference/python_api`
	`12`	`+ reference/tools`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+.. warning::`
	`2`	`+ The Conan API is experimental and subject to breaking changes.`