From 665918f22a1a71474bba2c08f325a49b05858b46 Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 18:55:12 -0400 Subject: [PATCH 01/20] initial doc skeleton --- Doc/cmake/index.rst | 18 ++++++ Doc/conf.py | 154 ++++++++++++++++++++++++++++++++++++++++++++ Doc/make.py | 78 ++++++++++++++++++++++ 3 files changed, 250 insertions(+) create mode 100644 Doc/cmake/index.rst create mode 100644 Doc/conf.py create mode 100644 Doc/make.py diff --git a/Doc/cmake/index.rst b/Doc/cmake/index.rst new file mode 100644 index 000000000..17a9ed416 --- /dev/null +++ b/Doc/cmake/index.rst @@ -0,0 +1,18 @@ +.. simple doc example + + +Welcome to python-cmake documentation! +====================================== + + +This is the documentation + + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/Doc/conf.py b/Doc/conf.py new file mode 100644 index 000000000..0b7df40c3 --- /dev/null +++ b/Doc/conf.py @@ -0,0 +1,154 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.mathjax', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'cmake/index' + +# General information about the project. +project = 'python-cmake-buildsystem' +copyright = 'Whatever' +author = 'A. Cavallo' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0.0' +# The full version, including alpha/beta/rc tags. +release = '1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'default' + + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'python-cmake-buildsystem' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'python-cmake-buildsystem.tex', 'python-cmake-buildsystem Documentation', + 'A. Cavallo', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'python-cmake-buildsystem', 'python-cmake-buildsystem Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'python-cmake-buildsystem', 'python-cmake-buildsystem Documentation', + author, 'python-cmake-buildsystem', 'One line description of project.', + 'Miscellaneous'), +] + + + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/Doc/make.py b/Doc/make.py new file mode 100644 index 000000000..ef1df1f8f --- /dev/null +++ b/Doc/make.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python +import sys +import os.path +import logging +import argparse + + +logger = logging.getLogger('main') + + +def npath(*parts): + if sys.platform != 'win32': + parts = [ a.replace('\\', ospath.sep) for a in parts ] + x = os.path.join(*parts) + x = os.path.expanduser(x) + x = os.path.normpath(x) + return x + + +def parse_args(args=None): + parser = argparse.ArgumentParser() + + workdir = npath(__file__, '..') + + parser.add_argument('dstdir', metavar='', nargs='?', + default=npath(workdir, '..', 'build', 'docs', 'html'), + help='output build directory') + + parser.add_argument('srcdir', metavar='', nargs='?', + default=npath(workdir), + help='input dource dir') + options = parser.parse_args(args) + + # sphinx related + options.confdir = workdir + + return options + + +def main(o): + from sphinx.util.docutils import docutils_namespace + from sphinx.application import Sphinx + + + doctreedir = npath(o.dstdir, '.doctrees') + builder = 'html' + + overrides = {} + overrides['version'] = '1.2.3' + overrides['release'] = '4' + #overrides['html_theme'] = 'classic' + + + status = sys.stdout + warning = sys.stderr + freshenv = True + + warningserror = None + tags = [] + verbosity = 0 + jobs = 0 + + force_all = True + filenames = [] + + + with docutils_namespace(): + app = Sphinx(o.srcdir, o.confdir, + o.dstdir, doctreedir, + builder, overrides, + status, warning, freshenv, + warningserror, tags, verbosity, jobs) + app.build(force_all, filenames) + return app.statuscode + + +if __name__ == '__main__': + sys.exit(main(parse_args()) or 0) From 5e2433fae7304805bb64dc83c27b702e9c08c027 Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 19:05:28 -0400 Subject: [PATCH 02/20] initial doc skeleton --- Doc/_static/.keepme | 0 Doc/_templates/.keepme | 0 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 Doc/_static/.keepme create mode 100644 Doc/_templates/.keepme diff --git a/Doc/_static/.keepme b/Doc/_static/.keepme new file mode 100644 index 000000000..e69de29bb diff --git a/Doc/_templates/.keepme b/Doc/_templates/.keepme new file mode 100644 index 000000000..e69de29bb From f2b6a5eb79643bf6e51c9d857cbb3e45e8600e8f Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 19:08:34 -0400 Subject: [PATCH 03/20] initial doc skeleton --- README.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.rst b/README.rst index 81419dc38..d52a4d08c 100644 --- a/README.rst +++ b/README.rst @@ -49,6 +49,18 @@ How to use this buildsystem: http://www.python.org/ftp/python/ +3. Creating documentation + +.. code:: bash + + python Doc/make.py + +.. note:: + + The output for documentation is under build/docs/html/cmake/index.html + + + CMake Options ------------- From 4c741ff80decda505ba81a26e096e44cdf496430 Mon Sep 17 00:00:00 2001 From: Isaiah Norton Date: Tue, 15 May 2018 11:48:07 -0400 Subject: [PATCH 04/20] Fix sqlite3 import by matching upstream build option for load_extension Per upstream documentation: > The sqlite3 module is not built with loadable extension support by > default, because some platforms (notably Mac OS X) have SQLite > libraries which are compiled without this feature. To get loadable > extension support, you must modify setup.py and remove the line that > sets SQLITE_OMIT_LOAD_EXTENSION. which means that SQLITE_OMIT_LOAD_EXTENSION is added as a compile definition by default in the upstream build system. We match that here to fix `import sqlite3`. --- cmake/extensions/CMakeLists.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cmake/extensions/CMakeLists.txt b/cmake/extensions/CMakeLists.txt index 8c12e0dce..301c9f226 100644 --- a/cmake/extensions/CMakeLists.txt +++ b/cmake/extensions/CMakeLists.txt @@ -640,7 +640,7 @@ add_python_extension(_sqlite3 _sqlite/row.c _sqlite/statement.c _sqlite/util.c - DEFINITIONS MODULE_NAME="sqlite3" + DEFINITIONS MODULE_NAME="sqlite3" SQLITE_OMIT_LOAD_EXTENSION=1 INCLUDEDIRS ${SQLITE3_INCLUDE_PATH} LIBRARIES ${SQLITE3_LIBRARY} ) From 57e0d814c01367f7bfb4343e2014b4dd85e45f7f Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 18:55:12 -0400 Subject: [PATCH 05/20] initial doc skeleton --- Doc/cmake/index.rst | 18 ++++++ Doc/conf.py | 154 ++++++++++++++++++++++++++++++++++++++++++++ Doc/make.py | 78 ++++++++++++++++++++++ 3 files changed, 250 insertions(+) create mode 100644 Doc/cmake/index.rst create mode 100644 Doc/conf.py create mode 100644 Doc/make.py diff --git a/Doc/cmake/index.rst b/Doc/cmake/index.rst new file mode 100644 index 000000000..17a9ed416 --- /dev/null +++ b/Doc/cmake/index.rst @@ -0,0 +1,18 @@ +.. simple doc example + + +Welcome to python-cmake documentation! +====================================== + + +This is the documentation + + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/Doc/conf.py b/Doc/conf.py new file mode 100644 index 000000000..0b7df40c3 --- /dev/null +++ b/Doc/conf.py @@ -0,0 +1,154 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.mathjax', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'cmake/index' + +# General information about the project. +project = 'python-cmake-buildsystem' +copyright = 'Whatever' +author = 'A. Cavallo' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0.0' +# The full version, including alpha/beta/rc tags. +release = '1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'default' + + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'python-cmake-buildsystem' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'python-cmake-buildsystem.tex', 'python-cmake-buildsystem Documentation', + 'A. Cavallo', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'python-cmake-buildsystem', 'python-cmake-buildsystem Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'python-cmake-buildsystem', 'python-cmake-buildsystem Documentation', + author, 'python-cmake-buildsystem', 'One line description of project.', + 'Miscellaneous'), +] + + + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/Doc/make.py b/Doc/make.py new file mode 100644 index 000000000..ef1df1f8f --- /dev/null +++ b/Doc/make.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python +import sys +import os.path +import logging +import argparse + + +logger = logging.getLogger('main') + + +def npath(*parts): + if sys.platform != 'win32': + parts = [ a.replace('\\', ospath.sep) for a in parts ] + x = os.path.join(*parts) + x = os.path.expanduser(x) + x = os.path.normpath(x) + return x + + +def parse_args(args=None): + parser = argparse.ArgumentParser() + + workdir = npath(__file__, '..') + + parser.add_argument('dstdir', metavar='', nargs='?', + default=npath(workdir, '..', 'build', 'docs', 'html'), + help='output build directory') + + parser.add_argument('srcdir', metavar='', nargs='?', + default=npath(workdir), + help='input dource dir') + options = parser.parse_args(args) + + # sphinx related + options.confdir = workdir + + return options + + +def main(o): + from sphinx.util.docutils import docutils_namespace + from sphinx.application import Sphinx + + + doctreedir = npath(o.dstdir, '.doctrees') + builder = 'html' + + overrides = {} + overrides['version'] = '1.2.3' + overrides['release'] = '4' + #overrides['html_theme'] = 'classic' + + + status = sys.stdout + warning = sys.stderr + freshenv = True + + warningserror = None + tags = [] + verbosity = 0 + jobs = 0 + + force_all = True + filenames = [] + + + with docutils_namespace(): + app = Sphinx(o.srcdir, o.confdir, + o.dstdir, doctreedir, + builder, overrides, + status, warning, freshenv, + warningserror, tags, verbosity, jobs) + app.build(force_all, filenames) + return app.statuscode + + +if __name__ == '__main__': + sys.exit(main(parse_args()) or 0) From e96b06ca63e5c4d834a6e2e6d00b37b839747c71 Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 19:05:28 -0400 Subject: [PATCH 06/20] initial doc skeleton --- Doc/_static/.keepme | 0 Doc/_templates/.keepme | 0 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 Doc/_static/.keepme create mode 100644 Doc/_templates/.keepme diff --git a/Doc/_static/.keepme b/Doc/_static/.keepme new file mode 100644 index 000000000..e69de29bb diff --git a/Doc/_templates/.keepme b/Doc/_templates/.keepme new file mode 100644 index 000000000..e69de29bb From b7edef3b64f5af88fc90643680e1a3587848e324 Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 19:08:34 -0400 Subject: [PATCH 07/20] initial doc skeleton --- README.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.rst b/README.rst index 81419dc38..d52a4d08c 100644 --- a/README.rst +++ b/README.rst @@ -49,6 +49,18 @@ How to use this buildsystem: http://www.python.org/ftp/python/ +3. Creating documentation + +.. code:: bash + + python Doc/make.py + +.. note:: + + The output for documentation is under build/docs/html/cmake/index.html + + + CMake Options ------------- From 9f41f2cf7fa28f996c7ee73b7f7daeeae8404c1d Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 18:55:12 -0400 Subject: [PATCH 08/20] initial doc skeleton --- Doc/cmake/index.rst | 18 ++++++ Doc/conf.py | 154 ++++++++++++++++++++++++++++++++++++++++++++ Doc/make.py | 78 ++++++++++++++++++++++ 3 files changed, 250 insertions(+) create mode 100644 Doc/cmake/index.rst create mode 100644 Doc/conf.py create mode 100644 Doc/make.py diff --git a/Doc/cmake/index.rst b/Doc/cmake/index.rst new file mode 100644 index 000000000..17a9ed416 --- /dev/null +++ b/Doc/cmake/index.rst @@ -0,0 +1,18 @@ +.. simple doc example + + +Welcome to python-cmake documentation! +====================================== + + +This is the documentation + + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/Doc/conf.py b/Doc/conf.py new file mode 100644 index 000000000..0b7df40c3 --- /dev/null +++ b/Doc/conf.py @@ -0,0 +1,154 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.mathjax', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'cmake/index' + +# General information about the project. +project = 'python-cmake-buildsystem' +copyright = 'Whatever' +author = 'A. Cavallo' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0.0' +# The full version, including alpha/beta/rc tags. +release = '1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'default' + + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'python-cmake-buildsystem' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'python-cmake-buildsystem.tex', 'python-cmake-buildsystem Documentation', + 'A. Cavallo', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'python-cmake-buildsystem', 'python-cmake-buildsystem Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'python-cmake-buildsystem', 'python-cmake-buildsystem Documentation', + author, 'python-cmake-buildsystem', 'One line description of project.', + 'Miscellaneous'), +] + + + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/Doc/make.py b/Doc/make.py new file mode 100644 index 000000000..ef1df1f8f --- /dev/null +++ b/Doc/make.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python +import sys +import os.path +import logging +import argparse + + +logger = logging.getLogger('main') + + +def npath(*parts): + if sys.platform != 'win32': + parts = [ a.replace('\\', ospath.sep) for a in parts ] + x = os.path.join(*parts) + x = os.path.expanduser(x) + x = os.path.normpath(x) + return x + + +def parse_args(args=None): + parser = argparse.ArgumentParser() + + workdir = npath(__file__, '..') + + parser.add_argument('dstdir', metavar='', nargs='?', + default=npath(workdir, '..', 'build', 'docs', 'html'), + help='output build directory') + + parser.add_argument('srcdir', metavar='', nargs='?', + default=npath(workdir), + help='input dource dir') + options = parser.parse_args(args) + + # sphinx related + options.confdir = workdir + + return options + + +def main(o): + from sphinx.util.docutils import docutils_namespace + from sphinx.application import Sphinx + + + doctreedir = npath(o.dstdir, '.doctrees') + builder = 'html' + + overrides = {} + overrides['version'] = '1.2.3' + overrides['release'] = '4' + #overrides['html_theme'] = 'classic' + + + status = sys.stdout + warning = sys.stderr + freshenv = True + + warningserror = None + tags = [] + verbosity = 0 + jobs = 0 + + force_all = True + filenames = [] + + + with docutils_namespace(): + app = Sphinx(o.srcdir, o.confdir, + o.dstdir, doctreedir, + builder, overrides, + status, warning, freshenv, + warningserror, tags, verbosity, jobs) + app.build(force_all, filenames) + return app.statuscode + + +if __name__ == '__main__': + sys.exit(main(parse_args()) or 0) From 6f4638069f53de03d7091eb173fe787510b32567 Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 19:05:28 -0400 Subject: [PATCH 09/20] initial doc skeleton --- Doc/_static/.keepme | 0 Doc/_templates/.keepme | 0 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 Doc/_static/.keepme create mode 100644 Doc/_templates/.keepme diff --git a/Doc/_static/.keepme b/Doc/_static/.keepme new file mode 100644 index 000000000..e69de29bb diff --git a/Doc/_templates/.keepme b/Doc/_templates/.keepme new file mode 100644 index 000000000..e69de29bb From dd70142d19596c7c0803ac5a506736a612f00c86 Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 19:08:34 -0400 Subject: [PATCH 10/20] initial doc skeleton --- README.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.rst b/README.rst index 81419dc38..d52a4d08c 100644 --- a/README.rst +++ b/README.rst @@ -49,6 +49,18 @@ How to use this buildsystem: http://www.python.org/ftp/python/ +3. Creating documentation + +.. code:: bash + + python Doc/make.py + +.. note:: + + The output for documentation is under build/docs/html/cmake/index.html + + + CMake Options ------------- From 7edb496e77caea2ca3844d2f2d69b4ef7623217d Mon Sep 17 00:00:00 2001 From: antonio Date: Thu, 17 May 2018 09:34:13 -0400 Subject: [PATCH 11/20] uses the same scikit sphinx extensions --- Doc/cmake/cmake-modules.rst | 22 ++ Doc/cmake/cmake-modules/CMakeChecks.rst | 4 + Doc/cmake/index.rst | 18 +- Doc/cmakelib.py | 393 ++++++++++++++++++++++++ Doc/conf.py | 8 +- cmake/CMakeChecks.cmake | 6 + 6 files changed, 446 insertions(+), 5 deletions(-) create mode 100644 Doc/cmake/cmake-modules.rst create mode 100644 Doc/cmake/cmake-modules/CMakeChecks.rst create mode 100644 Doc/cmakelib.py diff --git a/Doc/cmake/cmake-modules.rst b/Doc/cmake/cmake-modules.rst new file mode 100644 index 000000000..3c0f1a3fd --- /dev/null +++ b/Doc/cmake/cmake-modules.rst @@ -0,0 +1,22 @@ +============= +CMake modules +============= + +To facilitate the writing of ``CMakeLists.txt`` used to build +CPython C/C++/Cython extensions, **scikit-build** provides the following +CMake modules: + +.. toctree:: + :maxdepth: 1 + + cmake-modules/CMakeChecks + + +They can be included using ``find_package``: + +.. code-block:: cmake + + include(cmake/CMakeChecks.cmake) + + +For more details, see the respective documentation of each modules. \ No newline at end of file diff --git a/Doc/cmake/cmake-modules/CMakeChecks.rst b/Doc/cmake/cmake-modules/CMakeChecks.rst new file mode 100644 index 000000000..ea02b0661 --- /dev/null +++ b/Doc/cmake/cmake-modules/CMakeChecks.rst @@ -0,0 +1,4 @@ +CMakeChecks -- checks cmake is configured +----------------------------------------- + +.. cmake-module:: ../../../cmake/CMakeChecks.cmake diff --git a/Doc/cmake/index.rst b/Doc/cmake/index.rst index 17a9ed416..4e44ea39f 100644 --- a/Doc/cmake/index.rst +++ b/Doc/cmake/index.rst @@ -1,13 +1,27 @@ .. simple doc example - Welcome to python-cmake documentation! ====================================== +This is the documentation for the python cmake-based buildsystem. + +We list here all the instructions to: + + #. extend the cmake system + #. build python with different configurations + +Build cpython +~~~~~~~~~~~~~ + +TODO -This is the documentation +Extend the cmake system +~~~~~~~~~~~~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 2 + cmake-modules Indices and tables diff --git a/Doc/cmakelib.py b/Doc/cmakelib.py new file mode 100644 index 000000000..f34df43d9 --- /dev/null +++ b/Doc/cmakelib.py @@ -0,0 +1,393 @@ +# from https://github.com/scikit-build/scikit-build/blob/master/docs/cmake.py +#============================================================================= +# CMake - Cross Platform Makefile Generator +# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium +# +# Distributed under the OSI-approved BSD License (the "License"); +# see accompanying file Copyright.txt for details. +# +# This software is distributed WITHOUT ANY WARRANTY; without even the +# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +# See the License for more information. +#============================================================================= +import os +import re + +# Monkey patch for pygments reporting an error when generator expressions are +# used. +# https://bitbucket.org/birkenfeld/pygments-main/issue/942/cmake-generator-expressions-not-handled +from pygments.lexers import CMakeLexer +from pygments.token import Name, Operator +from pygments.lexer import bygroups +CMakeLexer.tokens["args"].append(('(\\$<)(.+?)(>)', + bygroups(Operator, Name.Variable, Operator))) + +# Monkey patch for sphinx generating invalid content for qcollectiongenerator +# https://bitbucket.org/birkenfeld/sphinx/issue/1435/qthelp-builder-should-htmlescape-keywords +from sphinx.util.pycompat import htmlescape +from sphinx.builders.qthelp import QtHelpBuilder +old_build_keywords = QtHelpBuilder.build_keywords +def new_build_keywords(self, title, refs, subitems): + old_items = old_build_keywords(self, title, refs, subitems) + new_items = [] + for item in old_items: + before, rest = item.split("ref=\"", 1) + ref, after = rest.split("\"") + if ("<" in ref and ">" in ref): + new_items.append(before + "ref=\"" + htmlescape(ref) + "\"" + after) + else: + new_items.append(item) + return new_items +QtHelpBuilder.build_keywords = new_build_keywords + + +from docutils.parsers.rst import Directive, directives +from docutils.transforms import Transform +try: + from docutils.utils.error_reporting import SafeString, ErrorString +except ImportError: + # error_reporting was not in utils before version 0.11: + from docutils.error_reporting import SafeString, ErrorString + +from docutils import io, nodes + +from sphinx.directives import ObjectDescription +from sphinx.domains import Domain, ObjType +from sphinx.roles import XRefRole +from sphinx.util.nodes import make_refnode +from sphinx import addnodes + +class CMakeModule(Directive): + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {'encoding': directives.encoding} + + def __init__(self, *args, **keys): + self.re_start = re.compile(r'^#\[(?P=*)\[\.rst:$') + Directive.__init__(self, *args, **keys) + + def run(self): + settings = self.state.document.settings + if not settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + + env = self.state.document.settings.env + rel_path, path = env.relfn2path(self.arguments[0]) + path = os.path.normpath(path) + encoding = self.options.get('encoding', settings.input_encoding) + e_handler = settings.input_encoding_error_handler + try: + settings.record_dependencies.add(path) + f = io.FileInput(source_path=path, encoding=encoding, + error_handler=e_handler) + except UnicodeEncodeError as error: + raise self.severe('Problems with "%s" directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % + (self.name, SafeString(path))) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + raw_lines = f.read().splitlines() + f.close() + rst = None + lines = [] + for line in raw_lines: + if rst is not None and rst != '#': + # Bracket mode: check for end bracket + pos = line.find(rst) + if pos >= 0: + if line[0] == '#': + line = '' + else: + line = line[0:pos] + rst = None + else: + # Line mode: check for .rst start (bracket or line) + m = self.re_start.match(line) + if m: + rst = ']%s]' % m.group('eq') + line = '' + elif line == '#.rst:': + rst = '#' + line = '' + elif rst == '#': + if line == '#' or line[:2] == '# ': + line = line[2:] + else: + rst = None + line = '' + elif rst is None: + line = '' + lines.append(line) + if rst is not None and rst != '#': + raise self.warning('"%s" found unclosed bracket "#[%s[.rst:" in %s' % + (self.name, rst[1:-1], path)) + self.state_machine.insert_input(lines, path) + return [] + +class _cmake_index_entry: + def __init__(self, desc): + self.desc = desc + + def __call__(self, title, targetid, main = 'main'): + return ('pair', u'%s ; %s' % (self.desc, title), targetid, main, None) + +_cmake_index_objs = { + 'command': _cmake_index_entry('command'), + 'generator': _cmake_index_entry('generator'), + 'manual': _cmake_index_entry('manual'), + 'module': _cmake_index_entry('module'), + 'policy': _cmake_index_entry('policy'), + 'prop_cache': _cmake_index_entry('cache property'), + 'prop_dir': _cmake_index_entry('directory property'), + 'prop_gbl': _cmake_index_entry('global property'), + 'prop_inst': _cmake_index_entry('installed file property'), + 'prop_sf': _cmake_index_entry('source file property'), + 'prop_test': _cmake_index_entry('test property'), + 'prop_tgt': _cmake_index_entry('target property'), + 'variable': _cmake_index_entry('variable'), + } + +def _cmake_object_inventory(env, document, line, objtype, targetid): + inv = env.domaindata['cmake']['objects'] + if targetid in inv: + document.reporter.warning( + 'CMake object "%s" also described in "%s".' % + (targetid, env.doc2path(inv[targetid][0])), line=line) + inv[targetid] = (env.docname, objtype) + +class CMakeTransform(Transform): + + # Run this transform early since we insert nodes we want + # treated as if they were written in the documents. + default_priority = 210 + + def __init__(self, document, startnode): + Transform.__init__(self, document, startnode) + self.titles = {} + + def parse_title(self, docname): + """Parse a document title as the first line starting in [A-Za-z0-9<] + or fall back to the document basename if no such line exists. + The cmake --help-*-list commands also depend on this convention. + Return the title or False if the document file does not exist. + """ + env = self.document.settings.env + title = self.titles.get(docname) + if title is None: + fname = os.path.join(env.srcdir, docname+'.rst') + try: + f = open(fname, 'r') + except IOError: + title = False + else: + for line in f: + if len(line) > 0 and (line[0].isalnum() or line[0] == '<'): + title = line.rstrip() + break + f.close() + if title is None: + title = os.path.basename(docname) + self.titles[docname] = title + return title + + def apply(self): + env = self.document.settings.env + + # Treat some documents as cmake domain objects. + objtype, sep, tail = env.docname.rpartition('/') + make_index_entry = _cmake_index_objs.get(objtype) + if make_index_entry: + title = self.parse_title(env.docname) + # Insert the object link target. + if objtype == 'command': + targetname = title.lower() + else: + targetname = title + targetid = '%s:%s' % (objtype, targetname) + targetnode = nodes.target('', '', ids=[targetid]) + self.document.note_explicit_target(targetnode) + self.document.insert(0, targetnode) + # Insert the object index entry. + indexnode = addnodes.index() + indexnode['entries'] = [make_index_entry(title, targetid)] + self.document.insert(0, indexnode) + # Add to cmake domain object inventory + _cmake_object_inventory(env, self.document, 1, objtype, targetid) + +class CMakeObject(ObjectDescription): + + def handle_signature(self, sig, signode): + # called from sphinx.directives.ObjectDescription.run() + signode += addnodes.desc_name(sig, sig) + return sig + + def add_target_and_index(self, name, sig, signode): + if self.objtype == 'command': + targetname = name.lower() + else: + targetname = name + targetid = '%s:%s' % (self.objtype, targetname) + if targetid not in self.state.document.ids: + signode['names'].append(targetid) + signode['ids'].append(targetid) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + _cmake_object_inventory(self.env, self.state.document, + self.lineno, self.objtype, targetid) + + make_index_entry = _cmake_index_objs.get(self.objtype) + if make_index_entry: + self.indexnode['entries'].append(make_index_entry(name, targetid)) + +class CMakeXRefRole(XRefRole): + + # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'. + _re = re.compile(r'^(.+?)(\s*)(?$', re.DOTALL) + _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL) + + def __call__(self, typ, rawtext, text, *args, **keys): + # Translate CMake command cross-references of the form: + # `command_name(SUB_COMMAND)` + # to have an explicit target: + # `command_name(SUB_COMMAND) ` + if typ == 'cmake:command': + m = CMakeXRefRole._re_sub.match(text) + if m: + text = '%s <%s>' % (text, m.group(1)) + # CMake cross-reference targets frequently contain '<' so escape + # any explicit `` with '<' not preceded by whitespace. + while True: + m = CMakeXRefRole._re.match(text) + if m and len(m.group(2)) == 0: + text = '%s\x00<%s>' % (m.group(1), m.group(3)) + else: + break + return XRefRole.__call__(self, typ, rawtext, text, *args, **keys) + + # We cannot insert index nodes using the result_nodes method + # because CMakeXRefRole is processed before substitution_reference + # nodes are evaluated so target nodes (with 'ids' fields) would be + # duplicated in each evaluted substitution replacement. The + # docutils substitution transform does not allow this. Instead we + # use our own CMakeXRefTransform below to add index entries after + # substitutions are completed. + # + # def result_nodes(self, document, env, node, is_ref): + # pass + +class CMakeXRefTransform(Transform): + + # Run this transform early since we insert nodes we want + # treated as if they were written in the documents, but + # after the sphinx (210) and docutils (220) substitutions. + default_priority = 221 + + def apply(self): + env = self.document.settings.env + + # Find CMake cross-reference nodes and add index and target + # nodes for them. + for ref in self.document.traverse(addnodes.pending_xref): + if not ref['refdomain'] == 'cmake': + continue + + objtype = ref['reftype'] + make_index_entry = _cmake_index_objs.get(objtype) + if not make_index_entry: + continue + + objname = ref['reftarget'] + targetnum = env.new_serialno('index-%s:%s' % (objtype, objname)) + + targetid = 'index-%s-%s:%s' % (targetnum, objtype, objname) + targetnode = nodes.target('', '', ids=[targetid]) + self.document.note_explicit_target(targetnode) + + indexnode = addnodes.index() + indexnode['entries'] = [make_index_entry(objname, targetid, '')] + ref.replace_self([indexnode, targetnode, ref]) + +class CMakeDomain(Domain): + """CMake domain.""" + name = 'cmake' + label = 'CMake' + object_types = { + 'command': ObjType('command', 'command'), + 'generator': ObjType('generator', 'generator'), + 'variable': ObjType('variable', 'variable'), + 'module': ObjType('module', 'module'), + 'policy': ObjType('policy', 'policy'), + 'prop_cache': ObjType('prop_cache', 'prop_cache'), + 'prop_dir': ObjType('prop_dir', 'prop_dir'), + 'prop_gbl': ObjType('prop_gbl', 'prop_gbl'), + 'prop_inst': ObjType('prop_inst', 'prop_inst'), + 'prop_sf': ObjType('prop_sf', 'prop_sf'), + 'prop_test': ObjType('prop_test', 'prop_test'), + 'prop_tgt': ObjType('prop_tgt', 'prop_tgt'), + 'manual': ObjType('manual', 'manual'), + } + directives = { + 'command': CMakeObject, + 'variable': CMakeObject, + # Other object types cannot be created except by the CMakeTransform + # 'generator': CMakeObject, + # 'module': CMakeObject, + # 'policy': CMakeObject, + # 'prop_cache': CMakeObject, + # 'prop_dir': CMakeObject, + # 'prop_gbl': CMakeObject, + # 'prop_inst': CMakeObject, + # 'prop_sf': CMakeObject, + # 'prop_test': CMakeObject, + # 'prop_tgt': CMakeObject, + # 'manual': CMakeObject, + } + roles = { + 'command': CMakeXRefRole(fix_parens = True, lowercase = True), + 'generator': CMakeXRefRole(), + 'variable': CMakeXRefRole(), + 'module': CMakeXRefRole(), + 'policy': CMakeXRefRole(), + 'prop_cache': CMakeXRefRole(), + 'prop_dir': CMakeXRefRole(), + 'prop_gbl': CMakeXRefRole(), + 'prop_inst': CMakeXRefRole(), + 'prop_sf': CMakeXRefRole(), + 'prop_test': CMakeXRefRole(), + 'prop_tgt': CMakeXRefRole(), + 'manual': CMakeXRefRole(), + } + initial_data = { + 'objects': {}, # fullname -> docname, objtype + } + + def clear_doc(self, docname): + to_clear = set() + for fullname, (fn, _) in self.data['objects'].items(): + if fn == docname: + to_clear.add(fullname) + for fullname in to_clear: + del self.data['objects'][fullname] + + def resolve_xref(self, env, fromdocname, builder, + typ, target, node, contnode): + targetid = '%s:%s' % (typ, target) + obj = self.data['objects'].get(targetid) + if obj is None: + # TODO: warn somehow? + return None + return make_refnode(builder, fromdocname, obj[0], targetid, + contnode, target) + + def get_objects(self): + for refname, (docname, type) in self.data['objects'].items(): + yield (refname, refname, type, docname, refname, 1) + +def setup(app): + app.add_directive('cmake-module', CMakeModule) + app.add_transform(CMakeTransform) + app.add_transform(CMakeXRefTransform) + app.add_domain(CMakeDomain) \ No newline at end of file diff --git a/Doc/conf.py b/Doc/conf.py index 0b7df40c3..6f52bb88b 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -2,10 +2,11 @@ # -*- coding: utf-8 -*- # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +sys.path.insert(0, os.path.abspath('.')) +import cmakelib # -- General configuration ------------------------------------------------ @@ -17,6 +18,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'cmakelib', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx', diff --git a/cmake/CMakeChecks.cmake b/cmake/CMakeChecks.cmake index 5abd055a2..6cccac09e 100644 --- a/cmake/CMakeChecks.cmake +++ b/cmake/CMakeChecks.cmake @@ -1,3 +1,9 @@ +#.rst: +# +# Make cmake checks. +# +# This module will check if a the cmake system is well configured. +# include(cmake/CheckCMakeCommandExists.cmake) include(cmake/CheckCMakePropertyExists.cmake) From 42b5ac0530f868edae07b445463f802efa6c1140 Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 18:55:12 -0400 Subject: [PATCH 12/20] initial doc skeleton --- Doc/cmake/index.rst | 18 ++++++ Doc/conf.py | 154 ++++++++++++++++++++++++++++++++++++++++++++ Doc/make.py | 78 ++++++++++++++++++++++ 3 files changed, 250 insertions(+) create mode 100644 Doc/cmake/index.rst create mode 100644 Doc/conf.py create mode 100644 Doc/make.py diff --git a/Doc/cmake/index.rst b/Doc/cmake/index.rst new file mode 100644 index 000000000..17a9ed416 --- /dev/null +++ b/Doc/cmake/index.rst @@ -0,0 +1,18 @@ +.. simple doc example + + +Welcome to python-cmake documentation! +====================================== + + +This is the documentation + + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` \ No newline at end of file diff --git a/Doc/conf.py b/Doc/conf.py new file mode 100644 index 000000000..0b7df40c3 --- /dev/null +++ b/Doc/conf.py @@ -0,0 +1,154 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.mathjax', + 'sphinx.ext.ifconfig', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'cmake/index' + +# General information about the project. +project = 'python-cmake-buildsystem' +copyright = 'Whatever' +author = 'A. Cavallo' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.0.0' +# The full version, including alpha/beta/rc tags. +release = '1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'default' + + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'python-cmake-buildsystem' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'python-cmake-buildsystem.tex', 'python-cmake-buildsystem Documentation', + 'A. Cavallo', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'python-cmake-buildsystem', 'python-cmake-buildsystem Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'python-cmake-buildsystem', 'python-cmake-buildsystem Documentation', + author, 'python-cmake-buildsystem', 'One line description of project.', + 'Miscellaneous'), +] + + + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/Doc/make.py b/Doc/make.py new file mode 100644 index 000000000..ef1df1f8f --- /dev/null +++ b/Doc/make.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python +import sys +import os.path +import logging +import argparse + + +logger = logging.getLogger('main') + + +def npath(*parts): + if sys.platform != 'win32': + parts = [ a.replace('\\', ospath.sep) for a in parts ] + x = os.path.join(*parts) + x = os.path.expanduser(x) + x = os.path.normpath(x) + return x + + +def parse_args(args=None): + parser = argparse.ArgumentParser() + + workdir = npath(__file__, '..') + + parser.add_argument('dstdir', metavar='', nargs='?', + default=npath(workdir, '..', 'build', 'docs', 'html'), + help='output build directory') + + parser.add_argument('srcdir', metavar='', nargs='?', + default=npath(workdir), + help='input dource dir') + options = parser.parse_args(args) + + # sphinx related + options.confdir = workdir + + return options + + +def main(o): + from sphinx.util.docutils import docutils_namespace + from sphinx.application import Sphinx + + + doctreedir = npath(o.dstdir, '.doctrees') + builder = 'html' + + overrides = {} + overrides['version'] = '1.2.3' + overrides['release'] = '4' + #overrides['html_theme'] = 'classic' + + + status = sys.stdout + warning = sys.stderr + freshenv = True + + warningserror = None + tags = [] + verbosity = 0 + jobs = 0 + + force_all = True + filenames = [] + + + with docutils_namespace(): + app = Sphinx(o.srcdir, o.confdir, + o.dstdir, doctreedir, + builder, overrides, + status, warning, freshenv, + warningserror, tags, verbosity, jobs) + app.build(force_all, filenames) + return app.statuscode + + +if __name__ == '__main__': + sys.exit(main(parse_args()) or 0) From 065b37cb9c23a2a564aab6816062dfb311fd8a80 Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 19:05:28 -0400 Subject: [PATCH 13/20] initial doc skeleton --- Doc/_static/.keepme | 0 Doc/_templates/.keepme | 0 2 files changed, 0 insertions(+), 0 deletions(-) create mode 100644 Doc/_static/.keepme create mode 100644 Doc/_templates/.keepme diff --git a/Doc/_static/.keepme b/Doc/_static/.keepme new file mode 100644 index 000000000..e69de29bb diff --git a/Doc/_templates/.keepme b/Doc/_templates/.keepme new file mode 100644 index 000000000..e69de29bb From 59cea9450f4f0ba649fb7ad8a33e3831a984ab46 Mon Sep 17 00:00:00 2001 From: antonio Date: Fri, 11 May 2018 19:08:34 -0400 Subject: [PATCH 14/20] initial doc skeleton --- README.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/README.rst b/README.rst index 81419dc38..d52a4d08c 100644 --- a/README.rst +++ b/README.rst @@ -49,6 +49,18 @@ How to use this buildsystem: http://www.python.org/ftp/python/ +3. Creating documentation + +.. code:: bash + + python Doc/make.py + +.. note:: + + The output for documentation is under build/docs/html/cmake/index.html + + + CMake Options ------------- From 5254a5987c98ee917dc155e450991b070d509c1c Mon Sep 17 00:00:00 2001 From: antonio Date: Thu, 17 May 2018 09:34:13 -0400 Subject: [PATCH 15/20] uses the same scikit sphinx extensions --- Doc/cmake/cmake-modules.rst | 22 ++ Doc/cmake/cmake-modules/CMakeChecks.rst | 4 + Doc/cmake/index.rst | 18 +- Doc/cmakelib.py | 393 ++++++++++++++++++++++++ Doc/conf.py | 8 +- cmake/CMakeChecks.cmake | 6 + 6 files changed, 446 insertions(+), 5 deletions(-) create mode 100644 Doc/cmake/cmake-modules.rst create mode 100644 Doc/cmake/cmake-modules/CMakeChecks.rst create mode 100644 Doc/cmakelib.py diff --git a/Doc/cmake/cmake-modules.rst b/Doc/cmake/cmake-modules.rst new file mode 100644 index 000000000..3c0f1a3fd --- /dev/null +++ b/Doc/cmake/cmake-modules.rst @@ -0,0 +1,22 @@ +============= +CMake modules +============= + +To facilitate the writing of ``CMakeLists.txt`` used to build +CPython C/C++/Cython extensions, **scikit-build** provides the following +CMake modules: + +.. toctree:: + :maxdepth: 1 + + cmake-modules/CMakeChecks + + +They can be included using ``find_package``: + +.. code-block:: cmake + + include(cmake/CMakeChecks.cmake) + + +For more details, see the respective documentation of each modules. \ No newline at end of file diff --git a/Doc/cmake/cmake-modules/CMakeChecks.rst b/Doc/cmake/cmake-modules/CMakeChecks.rst new file mode 100644 index 000000000..ea02b0661 --- /dev/null +++ b/Doc/cmake/cmake-modules/CMakeChecks.rst @@ -0,0 +1,4 @@ +CMakeChecks -- checks cmake is configured +----------------------------------------- + +.. cmake-module:: ../../../cmake/CMakeChecks.cmake diff --git a/Doc/cmake/index.rst b/Doc/cmake/index.rst index 17a9ed416..4e44ea39f 100644 --- a/Doc/cmake/index.rst +++ b/Doc/cmake/index.rst @@ -1,13 +1,27 @@ .. simple doc example - Welcome to python-cmake documentation! ====================================== +This is the documentation for the python cmake-based buildsystem. + +We list here all the instructions to: + + #. extend the cmake system + #. build python with different configurations + +Build cpython +~~~~~~~~~~~~~ + +TODO -This is the documentation +Extend the cmake system +~~~~~~~~~~~~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 2 + cmake-modules Indices and tables diff --git a/Doc/cmakelib.py b/Doc/cmakelib.py new file mode 100644 index 000000000..f34df43d9 --- /dev/null +++ b/Doc/cmakelib.py @@ -0,0 +1,393 @@ +# from https://github.com/scikit-build/scikit-build/blob/master/docs/cmake.py +#============================================================================= +# CMake - Cross Platform Makefile Generator +# Copyright 2000-2013 Kitware, Inc., Insight Software Consortium +# +# Distributed under the OSI-approved BSD License (the "License"); +# see accompanying file Copyright.txt for details. +# +# This software is distributed WITHOUT ANY WARRANTY; without even the +# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +# See the License for more information. +#============================================================================= +import os +import re + +# Monkey patch for pygments reporting an error when generator expressions are +# used. +# https://bitbucket.org/birkenfeld/pygments-main/issue/942/cmake-generator-expressions-not-handled +from pygments.lexers import CMakeLexer +from pygments.token import Name, Operator +from pygments.lexer import bygroups +CMakeLexer.tokens["args"].append(('(\\$<)(.+?)(>)', + bygroups(Operator, Name.Variable, Operator))) + +# Monkey patch for sphinx generating invalid content for qcollectiongenerator +# https://bitbucket.org/birkenfeld/sphinx/issue/1435/qthelp-builder-should-htmlescape-keywords +from sphinx.util.pycompat import htmlescape +from sphinx.builders.qthelp import QtHelpBuilder +old_build_keywords = QtHelpBuilder.build_keywords +def new_build_keywords(self, title, refs, subitems): + old_items = old_build_keywords(self, title, refs, subitems) + new_items = [] + for item in old_items: + before, rest = item.split("ref=\"", 1) + ref, after = rest.split("\"") + if ("<" in ref and ">" in ref): + new_items.append(before + "ref=\"" + htmlescape(ref) + "\"" + after) + else: + new_items.append(item) + return new_items +QtHelpBuilder.build_keywords = new_build_keywords + + +from docutils.parsers.rst import Directive, directives +from docutils.transforms import Transform +try: + from docutils.utils.error_reporting import SafeString, ErrorString +except ImportError: + # error_reporting was not in utils before version 0.11: + from docutils.error_reporting import SafeString, ErrorString + +from docutils import io, nodes + +from sphinx.directives import ObjectDescription +from sphinx.domains import Domain, ObjType +from sphinx.roles import XRefRole +from sphinx.util.nodes import make_refnode +from sphinx import addnodes + +class CMakeModule(Directive): + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {'encoding': directives.encoding} + + def __init__(self, *args, **keys): + self.re_start = re.compile(r'^#\[(?P=*)\[\.rst:$') + Directive.__init__(self, *args, **keys) + + def run(self): + settings = self.state.document.settings + if not settings.file_insertion_enabled: + raise self.warning('"%s" directive disabled.' % self.name) + + env = self.state.document.settings.env + rel_path, path = env.relfn2path(self.arguments[0]) + path = os.path.normpath(path) + encoding = self.options.get('encoding', settings.input_encoding) + e_handler = settings.input_encoding_error_handler + try: + settings.record_dependencies.add(path) + f = io.FileInput(source_path=path, encoding=encoding, + error_handler=e_handler) + except UnicodeEncodeError as error: + raise self.severe('Problems with "%s" directive path:\n' + 'Cannot encode input file path "%s" ' + '(wrong locale?).' % + (self.name, SafeString(path))) + except IOError as error: + raise self.severe('Problems with "%s" directive path:\n%s.' % + (self.name, ErrorString(error))) + raw_lines = f.read().splitlines() + f.close() + rst = None + lines = [] + for line in raw_lines: + if rst is not None and rst != '#': + # Bracket mode: check for end bracket + pos = line.find(rst) + if pos >= 0: + if line[0] == '#': + line = '' + else: + line = line[0:pos] + rst = None + else: + # Line mode: check for .rst start (bracket or line) + m = self.re_start.match(line) + if m: + rst = ']%s]' % m.group('eq') + line = '' + elif line == '#.rst:': + rst = '#' + line = '' + elif rst == '#': + if line == '#' or line[:2] == '# ': + line = line[2:] + else: + rst = None + line = '' + elif rst is None: + line = '' + lines.append(line) + if rst is not None and rst != '#': + raise self.warning('"%s" found unclosed bracket "#[%s[.rst:" in %s' % + (self.name, rst[1:-1], path)) + self.state_machine.insert_input(lines, path) + return [] + +class _cmake_index_entry: + def __init__(self, desc): + self.desc = desc + + def __call__(self, title, targetid, main = 'main'): + return ('pair', u'%s ; %s' % (self.desc, title), targetid, main, None) + +_cmake_index_objs = { + 'command': _cmake_index_entry('command'), + 'generator': _cmake_index_entry('generator'), + 'manual': _cmake_index_entry('manual'), + 'module': _cmake_index_entry('module'), + 'policy': _cmake_index_entry('policy'), + 'prop_cache': _cmake_index_entry('cache property'), + 'prop_dir': _cmake_index_entry('directory property'), + 'prop_gbl': _cmake_index_entry('global property'), + 'prop_inst': _cmake_index_entry('installed file property'), + 'prop_sf': _cmake_index_entry('source file property'), + 'prop_test': _cmake_index_entry('test property'), + 'prop_tgt': _cmake_index_entry('target property'), + 'variable': _cmake_index_entry('variable'), + } + +def _cmake_object_inventory(env, document, line, objtype, targetid): + inv = env.domaindata['cmake']['objects'] + if targetid in inv: + document.reporter.warning( + 'CMake object "%s" also described in "%s".' % + (targetid, env.doc2path(inv[targetid][0])), line=line) + inv[targetid] = (env.docname, objtype) + +class CMakeTransform(Transform): + + # Run this transform early since we insert nodes we want + # treated as if they were written in the documents. + default_priority = 210 + + def __init__(self, document, startnode): + Transform.__init__(self, document, startnode) + self.titles = {} + + def parse_title(self, docname): + """Parse a document title as the first line starting in [A-Za-z0-9<] + or fall back to the document basename if no such line exists. + The cmake --help-*-list commands also depend on this convention. + Return the title or False if the document file does not exist. + """ + env = self.document.settings.env + title = self.titles.get(docname) + if title is None: + fname = os.path.join(env.srcdir, docname+'.rst') + try: + f = open(fname, 'r') + except IOError: + title = False + else: + for line in f: + if len(line) > 0 and (line[0].isalnum() or line[0] == '<'): + title = line.rstrip() + break + f.close() + if title is None: + title = os.path.basename(docname) + self.titles[docname] = title + return title + + def apply(self): + env = self.document.settings.env + + # Treat some documents as cmake domain objects. + objtype, sep, tail = env.docname.rpartition('/') + make_index_entry = _cmake_index_objs.get(objtype) + if make_index_entry: + title = self.parse_title(env.docname) + # Insert the object link target. + if objtype == 'command': + targetname = title.lower() + else: + targetname = title + targetid = '%s:%s' % (objtype, targetname) + targetnode = nodes.target('', '', ids=[targetid]) + self.document.note_explicit_target(targetnode) + self.document.insert(0, targetnode) + # Insert the object index entry. + indexnode = addnodes.index() + indexnode['entries'] = [make_index_entry(title, targetid)] + self.document.insert(0, indexnode) + # Add to cmake domain object inventory + _cmake_object_inventory(env, self.document, 1, objtype, targetid) + +class CMakeObject(ObjectDescription): + + def handle_signature(self, sig, signode): + # called from sphinx.directives.ObjectDescription.run() + signode += addnodes.desc_name(sig, sig) + return sig + + def add_target_and_index(self, name, sig, signode): + if self.objtype == 'command': + targetname = name.lower() + else: + targetname = name + targetid = '%s:%s' % (self.objtype, targetname) + if targetid not in self.state.document.ids: + signode['names'].append(targetid) + signode['ids'].append(targetid) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + _cmake_object_inventory(self.env, self.state.document, + self.lineno, self.objtype, targetid) + + make_index_entry = _cmake_index_objs.get(self.objtype) + if make_index_entry: + self.indexnode['entries'].append(make_index_entry(name, targetid)) + +class CMakeXRefRole(XRefRole): + + # See sphinx.util.nodes.explicit_title_re; \x00 escapes '<'. + _re = re.compile(r'^(.+?)(\s*)(?$', re.DOTALL) + _re_sub = re.compile(r'^([^()\s]+)\s*\(([^()]*)\)$', re.DOTALL) + + def __call__(self, typ, rawtext, text, *args, **keys): + # Translate CMake command cross-references of the form: + # `command_name(SUB_COMMAND)` + # to have an explicit target: + # `command_name(SUB_COMMAND) ` + if typ == 'cmake:command': + m = CMakeXRefRole._re_sub.match(text) + if m: + text = '%s <%s>' % (text, m.group(1)) + # CMake cross-reference targets frequently contain '<' so escape + # any explicit `` with '<' not preceded by whitespace. + while True: + m = CMakeXRefRole._re.match(text) + if m and len(m.group(2)) == 0: + text = '%s\x00<%s>' % (m.group(1), m.group(3)) + else: + break + return XRefRole.__call__(self, typ, rawtext, text, *args, **keys) + + # We cannot insert index nodes using the result_nodes method + # because CMakeXRefRole is processed before substitution_reference + # nodes are evaluated so target nodes (with 'ids' fields) would be + # duplicated in each evaluted substitution replacement. The + # docutils substitution transform does not allow this. Instead we + # use our own CMakeXRefTransform below to add index entries after + # substitutions are completed. + # + # def result_nodes(self, document, env, node, is_ref): + # pass + +class CMakeXRefTransform(Transform): + + # Run this transform early since we insert nodes we want + # treated as if they were written in the documents, but + # after the sphinx (210) and docutils (220) substitutions. + default_priority = 221 + + def apply(self): + env = self.document.settings.env + + # Find CMake cross-reference nodes and add index and target + # nodes for them. + for ref in self.document.traverse(addnodes.pending_xref): + if not ref['refdomain'] == 'cmake': + continue + + objtype = ref['reftype'] + make_index_entry = _cmake_index_objs.get(objtype) + if not make_index_entry: + continue + + objname = ref['reftarget'] + targetnum = env.new_serialno('index-%s:%s' % (objtype, objname)) + + targetid = 'index-%s-%s:%s' % (targetnum, objtype, objname) + targetnode = nodes.target('', '', ids=[targetid]) + self.document.note_explicit_target(targetnode) + + indexnode = addnodes.index() + indexnode['entries'] = [make_index_entry(objname, targetid, '')] + ref.replace_self([indexnode, targetnode, ref]) + +class CMakeDomain(Domain): + """CMake domain.""" + name = 'cmake' + label = 'CMake' + object_types = { + 'command': ObjType('command', 'command'), + 'generator': ObjType('generator', 'generator'), + 'variable': ObjType('variable', 'variable'), + 'module': ObjType('module', 'module'), + 'policy': ObjType('policy', 'policy'), + 'prop_cache': ObjType('prop_cache', 'prop_cache'), + 'prop_dir': ObjType('prop_dir', 'prop_dir'), + 'prop_gbl': ObjType('prop_gbl', 'prop_gbl'), + 'prop_inst': ObjType('prop_inst', 'prop_inst'), + 'prop_sf': ObjType('prop_sf', 'prop_sf'), + 'prop_test': ObjType('prop_test', 'prop_test'), + 'prop_tgt': ObjType('prop_tgt', 'prop_tgt'), + 'manual': ObjType('manual', 'manual'), + } + directives = { + 'command': CMakeObject, + 'variable': CMakeObject, + # Other object types cannot be created except by the CMakeTransform + # 'generator': CMakeObject, + # 'module': CMakeObject, + # 'policy': CMakeObject, + # 'prop_cache': CMakeObject, + # 'prop_dir': CMakeObject, + # 'prop_gbl': CMakeObject, + # 'prop_inst': CMakeObject, + # 'prop_sf': CMakeObject, + # 'prop_test': CMakeObject, + # 'prop_tgt': CMakeObject, + # 'manual': CMakeObject, + } + roles = { + 'command': CMakeXRefRole(fix_parens = True, lowercase = True), + 'generator': CMakeXRefRole(), + 'variable': CMakeXRefRole(), + 'module': CMakeXRefRole(), + 'policy': CMakeXRefRole(), + 'prop_cache': CMakeXRefRole(), + 'prop_dir': CMakeXRefRole(), + 'prop_gbl': CMakeXRefRole(), + 'prop_inst': CMakeXRefRole(), + 'prop_sf': CMakeXRefRole(), + 'prop_test': CMakeXRefRole(), + 'prop_tgt': CMakeXRefRole(), + 'manual': CMakeXRefRole(), + } + initial_data = { + 'objects': {}, # fullname -> docname, objtype + } + + def clear_doc(self, docname): + to_clear = set() + for fullname, (fn, _) in self.data['objects'].items(): + if fn == docname: + to_clear.add(fullname) + for fullname in to_clear: + del self.data['objects'][fullname] + + def resolve_xref(self, env, fromdocname, builder, + typ, target, node, contnode): + targetid = '%s:%s' % (typ, target) + obj = self.data['objects'].get(targetid) + if obj is None: + # TODO: warn somehow? + return None + return make_refnode(builder, fromdocname, obj[0], targetid, + contnode, target) + + def get_objects(self): + for refname, (docname, type) in self.data['objects'].items(): + yield (refname, refname, type, docname, refname, 1) + +def setup(app): + app.add_directive('cmake-module', CMakeModule) + app.add_transform(CMakeTransform) + app.add_transform(CMakeXRefTransform) + app.add_domain(CMakeDomain) \ No newline at end of file diff --git a/Doc/conf.py b/Doc/conf.py index 0b7df40c3..6f52bb88b 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -2,10 +2,11 @@ # -*- coding: utf-8 -*- # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import os +import sys +sys.path.insert(0, os.path.abspath('.')) +import cmakelib # -- General configuration ------------------------------------------------ @@ -17,6 +18,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'cmakelib', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx', diff --git a/cmake/CMakeChecks.cmake b/cmake/CMakeChecks.cmake index 5abd055a2..6cccac09e 100644 --- a/cmake/CMakeChecks.cmake +++ b/cmake/CMakeChecks.cmake @@ -1,3 +1,9 @@ +#.rst: +# +# Make cmake checks. +# +# This module will check if a the cmake system is well configured. +# include(cmake/CheckCMakeCommandExists.cmake) include(cmake/CheckCMakePropertyExists.cmake) From 33cb63e9eca05242582b0e4777565b2c173e468d Mon Sep 17 00:00:00 2001 From: antonio Date: Tue, 22 May 2018 22:01:32 -0400 Subject: [PATCH 16/20] added cmake documentation --- cmake/CMakeChecks.cmake | 7 +++++-- cmake/CheckCMakeCommandExists.cmake | 14 ++++++++++++++ 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/cmake/CMakeChecks.cmake b/cmake/CMakeChecks.cmake index 6cccac09e..4e213c121 100644 --- a/cmake/CMakeChecks.cmake +++ b/cmake/CMakeChecks.cmake @@ -1,8 +1,11 @@ #.rst: # -# Make cmake checks. +# ================================= +# CMakeChecks --- init the builtool +# ================================= # -# This module will check if a the cmake system is well configured. +# This module will cimport some macros and wiil +# perform some pre-flight checks. # include(cmake/CheckCMakeCommandExists.cmake) diff --git a/cmake/CheckCMakeCommandExists.cmake b/cmake/CheckCMakeCommandExists.cmake index a8d299e7b..ded944c4e 100644 --- a/cmake/CheckCMakeCommandExists.cmake +++ b/cmake/CheckCMakeCommandExists.cmake @@ -1,3 +1,17 @@ +#.rst: +# +# ======================================================================== +# CheckCMakeCommandExists --- test if an internal cmake command is present +# ======================================================================== +# +# This test will verify a cmake command is present +# +# .. code-block:: cmake +# +# include(cmake-modules/CMakeChecks.cmake) +# +# + macro(check_cmake_command_exists commandname) string(TOUPPER ${commandname} commandname_upper) From 4ca0b6c535e65bea5654af912774f489a166c17e Mon Sep 17 00:00:00 2001 From: antonio Date: Tue, 22 May 2018 22:02:31 -0400 Subject: [PATCH 17/20] backport cpython document build script, align the conf.py to the cpython version --- Doc/conf.py | 5 ++- Doc/make.py | 126 ++++++++++++++++++++++++++++++++++++++++------------ 2 files changed, 102 insertions(+), 29 deletions(-) diff --git a/Doc/conf.py b/Doc/conf.py index 6f52bb88b..f63b191aa 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -5,8 +5,11 @@ import os import sys sys.path.insert(0, os.path.abspath('.')) +import sys, os, time +sys.path.append(os.path.abspath('tools/extensions')) +sys.path.append(os.path.abspath('includes')) + -import cmakelib # -- General configuration ------------------------------------------------ diff --git a/Doc/make.py b/Doc/make.py index ef1df1f8f..849b18967 100644 --- a/Doc/make.py +++ b/Doc/make.py @@ -1,9 +1,57 @@ #!/usr/bin/env python +"""alternative build script for python documentation. + +This script runs the sphix documentation build. + +Example: + $> make.py + +In python for python. +""" + +#TODO adds blurb support + import sys import os.path import logging +import textwrap import argparse +# dependencies +try: + import sphinx +except ImportError: + print(""" +The 'sphinx-build' command was not found. Make sure you have Sphinx +installed, then set the SPHINXBUILD environment variable to point +to the full path of the 'sphinx-build' executable. Alternatively you +may add the Sphinx directory to PATH. + +If you don't have Sphinx installed, grab it from + http://sphinx-doc.org/ +""" +) + sys.exit(1) + +try: + import blurb +except ImportError: + print(""" +The blurb package was not found. +Installing blurb with + {e} -m pip install blurb + +""".format(e=sys.executable) +) + sys.exit(1) + + +# The script begins here!! + +from sphinx.util.docutils import docutils_namespace +from sphinx.application import Sphinx +from sphinx.util.console import nocolor + logger = logging.getLogger('main') @@ -17,62 +65,84 @@ def npath(*parts): return x -def parse_args(args=None): - parser = argparse.ArgumentParser() - - workdir = npath(__file__, '..') - - parser.add_argument('dstdir', metavar='', nargs='?', - default=npath(workdir, '..', 'build', 'docs', 'html'), - help='output build directory') - - parser.add_argument('srcdir', metavar='', nargs='?', - default=npath(workdir), - help='input dource dir') - options = parser.parse_args(args) - - # sphinx related - options.confdir = workdir - - return options +def split_doc(txt): + if not txt: + return '', '' + descr, _, epi = txt.lstrip().partition('\n') + epi = textwrap.dedent(epi) + return descr, epi.strip() def main(o): - from sphinx.util.docutils import docutils_namespace - from sphinx.application import Sphinx - - doctreedir = npath(o.dstdir, '.doctrees') builder = 'html' overrides = {} - overrides['version'] = '1.2.3' - overrides['release'] = '4' + #overrides['version'] = '1.2.3' + #overrides['release'] = '4' + #overrides['html_theme'] = 'classic' status = sys.stdout warning = sys.stderr - freshenv = True + freshenv = False warningserror = None tags = [] verbosity = 0 jobs = 0 - force_all = True - filenames = [] + force_all = o.force + filenames = o.filenames + nocolor() with docutils_namespace(): app = Sphinx(o.srcdir, o.confdir, - o.dstdir, doctreedir, + o.dstdir, o.doctrees, builder, overrides, status, warning, freshenv, warningserror, tags, verbosity, jobs) app.build(force_all, filenames) return app.statuscode + +def parse_args(args=None): + description, epilog = split_doc(__doc__) + class StandardFormatter(argparse.ArgumentDefaultsHelpFormatter, + argparse.RawDescriptionHelpFormatter): + pass + parser = argparse.ArgumentParser(formatter_class=StandardFormatter, + description=description, epilog=epilog) + + workdir = npath(__file__, '..') + parser.add_argument('-f', '--force', action='store_true', default=False, + help='force all nodes rebuild') + + parser.add_argument('-d', '--doctrees', metavar='', nargs='?', + default=npath(workdir, 'build', 'doctrees'), + help='output build directory') + parser.add_argument('-o', '--output', dest='dstdir', metavar='', + default=npath(workdir, 'build', 'html'), + help='output build directory') + parser.add_argument('-i', '--srcdir', metavar='', + default=npath(workdir), + help='input dource dir') + + parser.add_argument('filenames', nargs='*') + + options = parser.parse_args(args) + + # sphinx directory containing the config file + options.confdir = workdir + + filenames = [] + for f in options.filenames or []: + filenames.append(npath(f, 'index') if os.path.isdir(f) else f) + options.filenames = filenames + return options + if __name__ == '__main__': sys.exit(main(parse_args()) or 0) From 357aad2fae16901d41e924067978e896cd0b83b8 Mon Sep 17 00:00:00 2001 From: antonio Date: Tue, 22 May 2018 22:02:48 -0400 Subject: [PATCH 18/20] backport cpython document build script, align the cmakelib.py to the cpython version --- Doc/{ => tools/extensions}/cmakelib.py | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Doc/{ => tools/extensions}/cmakelib.py (100%) diff --git a/Doc/cmakelib.py b/Doc/tools/extensions/cmakelib.py similarity index 100% rename from Doc/cmakelib.py rename to Doc/tools/extensions/cmakelib.py From d49d2315a08cd57a799e43843778944fba43579b Mon Sep 17 00:00:00 2001 From: antonio Date: Tue, 22 May 2018 22:03:22 -0400 Subject: [PATCH 19/20] added more documentation (backport from cpython) --- Doc/cmake/cmake-modules.rst | 48 +++++++++++++++++++------ Doc/cmake/cmake-modules/CMakeChecks.rst | 4 --- Doc/cmake/index.rst | 46 +++++++++++++++++------- 3 files changed, 71 insertions(+), 27 deletions(-) delete mode 100644 Doc/cmake/cmake-modules/CMakeChecks.rst diff --git a/Doc/cmake/cmake-modules.rst b/Doc/cmake/cmake-modules.rst index 3c0f1a3fd..5182e119d 100644 --- a/Doc/cmake/cmake-modules.rst +++ b/Doc/cmake/cmake-modules.rst @@ -1,22 +1,48 @@ -============= -CMake modules -============= +Modifying CMakeList.txt and using cmake modules +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To facilitate the writing of ``CMakeLists.txt`` used to build -CPython C/C++/Cython extensions, **scikit-build** provides the following -CMake modules: +The central configuration cmake file is the ``CMakeLists.txt``, this is a Makefile equivalent, +with added funcionalities. -.. toctree:: - :maxdepth: 1 +The ``CMakeLists.txt`` can import and use support modules (usually ending with the *.cmake* prefix and locate under the +main tree: - cmake-modules/CMakeChecks +.. code-block:: shell-session + + ├───CMakeLists.txt <- main cmake configuration file + ├───cmake <- ``CMakeLists.txt`` support files + ├───Doc + │ ├───cmake <- cmake documentation + │ ├───tutorial + │ ├───using + │ └───whatsnew + ├───Grammar + ├───Include + ..... + ├───Python + │ └───clinic + └───Tools -They can be included using ``find_package``: + +``CMakeLists.txt`` + +To facilitate the writing of ``CMakeLists.txt`` cmake modules can be used. In order to make +use of them, it is necessary to include them using the cmake command ``find_package`` from within ``CMakeLists.txt``: .. code-block:: cmake include(cmake/CMakeChecks.cmake) -For more details, see the respective documentation of each modules. \ No newline at end of file +List of support modules +~~~~~~~~~~~~~~~~~~~~~~~ + +For more details, see each modue documentation. + + +.. cmake-module:: ../../cmake/CMakeChecks.cmake +.. cmake-module:: ../../cmake/CheckCMakePropertyExists.cmake +.. cmake-module:: ../../cmake/CheckCMakeCommandExists.cmake + + diff --git a/Doc/cmake/cmake-modules/CMakeChecks.rst b/Doc/cmake/cmake-modules/CMakeChecks.rst deleted file mode 100644 index ea02b0661..000000000 --- a/Doc/cmake/cmake-modules/CMakeChecks.rst +++ /dev/null @@ -1,4 +0,0 @@ -CMakeChecks -- checks cmake is configured ------------------------------------------ - -.. cmake-module:: ../../../cmake/CMakeChecks.cmake diff --git a/Doc/cmake/index.rst b/Doc/cmake/index.rst index 4e44ea39f..aef29b9c0 100644 --- a/Doc/cmake/index.rst +++ b/Doc/cmake/index.rst @@ -1,22 +1,44 @@ -.. simple doc example +.. _cmake-index: -Welcome to python-cmake documentation! -====================================== +############################### +Building the python interpreter +############################### -This is the documentation for the python cmake-based buildsystem. +This is the documentation for the `CMake `_-based buildsystem. -We list here all the instructions to: +There are two parts to this document: - #. extend the cmake system - #. build python with different configurations + #. instructions for python developer (**Build instructions**) + #. documenttaion for **extending the build tool itself** -Build cpython -~~~~~~~~~~~~~ +In both cases you need to `download `_ and install cmake. -TODO -Extend the cmake system -~~~~~~~~~~~~~~~~~~~~~~~ +Build instructions +------------------ + +On Unix, Linux, BSD, macOS, and Cygwin:: + + mkdir build + cd build + cmake .. + make + + +On Windows: + +.. code-block:: shell-session + + md build + cd build + cmake -G "NMake Makefiles" .. + nmake + + +Extending the buildtool system +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The cmake base buildtool can be adapted and extended using the cmake syntax: .. toctree:: :maxdepth: 2 From 90743199a187102b7bbad19cd8848073230340cb Mon Sep 17 00:00:00 2001 From: antonio Date: Thu, 24 May 2018 20:59:20 -0400 Subject: [PATCH 20/20] update modules documentation --- Doc/cmake/cmake-modules.rst | 12 ++++++--- Doc/cmake/modules/CMakeChecks.rst | 1 + Doc/cmake/modules/CheckCMakeCommandExists.rst | 1 + Doc/cmake/modules/PythonApplyPatches.rst | 1 + cmake/CMakeChecks.cmake | 15 +++++++---- cmake/CheckCMakeCommandExists.cmake | 15 ++++++++--- cmake/PythonApplyPatches.cmake | 26 +++++++++++++++++++ 7 files changed, 58 insertions(+), 13 deletions(-) create mode 100644 Doc/cmake/modules/CMakeChecks.rst create mode 100644 Doc/cmake/modules/CheckCMakeCommandExists.rst create mode 100644 Doc/cmake/modules/PythonApplyPatches.rst diff --git a/Doc/cmake/cmake-modules.rst b/Doc/cmake/cmake-modules.rst index 5182e119d..758e5ac1b 100644 --- a/Doc/cmake/cmake-modules.rst +++ b/Doc/cmake/cmake-modules.rst @@ -38,11 +38,15 @@ use of them, it is necessary to include them using the cmake command ``find_pack List of support modules ~~~~~~~~~~~~~~~~~~~~~~~ -For more details, see each modue documentation. +For more details, see each module documentation. + +.. toctree:: + :maxdepth: 2 + + modules/CheckCMakeCommandExists + modules/CMakeChecks + modules/PythonApplyPatches -.. cmake-module:: ../../cmake/CMakeChecks.cmake -.. cmake-module:: ../../cmake/CheckCMakePropertyExists.cmake -.. cmake-module:: ../../cmake/CheckCMakeCommandExists.cmake diff --git a/Doc/cmake/modules/CMakeChecks.rst b/Doc/cmake/modules/CMakeChecks.rst new file mode 100644 index 000000000..0c3249ad7 --- /dev/null +++ b/Doc/cmake/modules/CMakeChecks.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../../cmake/CMakeChecks.cmake diff --git a/Doc/cmake/modules/CheckCMakeCommandExists.rst b/Doc/cmake/modules/CheckCMakeCommandExists.rst new file mode 100644 index 000000000..ec19e331f --- /dev/null +++ b/Doc/cmake/modules/CheckCMakeCommandExists.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../../cmake/CheckCMakeCommandExists.cmake diff --git a/Doc/cmake/modules/PythonApplyPatches.rst b/Doc/cmake/modules/PythonApplyPatches.rst new file mode 100644 index 000000000..9a276c6f3 --- /dev/null +++ b/Doc/cmake/modules/PythonApplyPatches.rst @@ -0,0 +1 @@ +.. cmake-module:: ../../../cmake/PythonApplyPatches.cmake diff --git a/cmake/CMakeChecks.cmake b/cmake/CMakeChecks.cmake index 4e213c121..5c26fe7ae 100644 --- a/cmake/CMakeChecks.cmake +++ b/cmake/CMakeChecks.cmake @@ -1,12 +1,17 @@ #.rst: # -# ================================= -# CMakeChecks --- init the builtool -# ================================= +# ============================== +# CMakeChecks - buildtool checks +# ============================== # -# This module will cimport some macros and wiil -# perform some pre-flight checks. +# This module imports some extra modules and performs the +# checks to the build tool # +# .. code-block:: cmake +# +# include(cmake/CMakeChecks.cmake) +# + include(cmake/CheckCMakeCommandExists.cmake) include(cmake/CheckCMakePropertyExists.cmake) diff --git a/cmake/CheckCMakeCommandExists.cmake b/cmake/CheckCMakeCommandExists.cmake index ded944c4e..e86537b6e 100644 --- a/cmake/CheckCMakeCommandExists.cmake +++ b/cmake/CheckCMakeCommandExists.cmake @@ -1,15 +1,22 @@ #.rst: # -# ======================================================================== -# CheckCMakeCommandExists --- test if an internal cmake command is present -# ======================================================================== +# =================================================== +# CheckCMakeCommandExists - check for a cmake command +# =================================================== # # This test will verify a cmake command is present # # .. code-block:: cmake # -# include(cmake-modules/CMakeChecks.cmake) +# include(cmake-modules/CMakeChecks.cmake) +# check_cmake_command_exists(hello) # +# .. code-block:: shell-session +# +# -- Looking for CMake command hello +# -- Looking for CMake command hello - not found +# +# On success **HAVE_HELLO** will be set to **ON** # diff --git a/cmake/PythonApplyPatches.cmake b/cmake/PythonApplyPatches.cmake index ea0be1182..1c31b4db0 100644 --- a/cmake/PythonApplyPatches.cmake +++ b/cmake/PythonApplyPatches.cmake @@ -1,3 +1,29 @@ +#.rst: +# +# ======================================================= +# PythonApplyPatches - apply patches to the python source +# ======================================================= +# +# This module apply patches to the python source code. +# +# +# The following variables are used: +# :: +# +# PATCH_COMMAND - sets the patch command to use +# (if running from a git checkout uses git apply) +# +# +# .. note:: +# +# patches are applied from the ?? subdirectory +# +# +# .. code-block:: cmake +# +# include(cmake/PythonApplyPatches.cmake) + + set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_LIST_DIR}