From fe3249bae6273a52ce776ca07ebe300218981fe1 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann Date: Fri, 1 May 2020 20:51:11 +0200 Subject: [PATCH 01/17] Build on Read the Docs --- .gitmodules | 5 +++ .readthedocs.yml | 19 +++++++++++ conf.py | 84 ++++++++++++++++++++++++++++++++++++++++++++++++ requirements.txt | 4 +++ 4 files changed, 112 insertions(+) create mode 100644 .gitmodules create mode 100644 .readthedocs.yml create mode 100644 conf.py create mode 100644 requirements.txt diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000000..f5517ef7c9 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,5 @@ +[submodule "cpython"] + path = cpython + url = https://github.com/python/cpython.git + branch = 3.7 + shallow = true diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000000..f8bfd6bd18 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,19 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: cpython/Doc/conf.py + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: requirements.txt + +submodules: + include: all diff --git a/conf.py b/conf.py new file mode 100644 index 0000000000..715aa4788b --- /dev/null +++ b/conf.py @@ -0,0 +1,84 @@ +import sys, os, time +sys.path.append(os.path.abspath('cpython/Doc/tools/extensions')) +sys.path.append(os.path.abspath('cpython/Doc/includes')) + +# General configuration +# --------------------- + +extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest', + 'pyspecific', 'c_annotations', 'escape4chm'] + + +project = 'Python en Español' +copyright = '2001-%s, Python Software Foundation' % time.strftime('%Y') + +release = version = 3.7 + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +today = '' +# Else, today_fmt is used as the format for a strftime call. +today_fmt = '%B %d, %Y' + +# By default, highlight as Python 3. +highlight_language = 'python3' + +# Minimum version of sphinx required +needs_sphinx = '1.8' + +# Ignore any .rst files in the venv/ directory. +exclude_patterns = ['venv/*', 'README.rst'] + +# Avoid a warning with Sphinx >= 2.0 +master_doc = 'contents' + +# Use our custom theme. +html_theme = 'python_docs_theme' +html_theme_path = ['cpython/Doc/tools'] +html_theme_options = { + 'collapsiblesidebar': True, + 'issues_url': 'https://docs.python.org/3/bugs.html', + 'root_include_title': False # We use the version switcher instead. +} + +# Short title used e.g. for HTML tags. +html_short_title = '%s Documentation' % release + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y' + +# Path to find HTML templates. +templates_path = ['cpython/Doc/tools/templates'] + +# Custom sidebar templates, filenames relative to this file. +html_sidebars = { + # Defaults taken from http://www.sphinx-doc.org/en/stable/config.html#confval-html_sidebars + # Removes the quick search block + '**': ['localtoc.html', 'relations.html', 'customsourcelink.html'], + 'index': ['indexsidebar.html'], +} + +# Additional templates that should be rendered to pages. +html_additional_pages = { + 'download': 'download.html', + 'index': 'indexcontent.html', +} + +# Output an OpenSearch description file. +html_use_opensearch = 'https://docs.python.org/' + version + +# Additional static files. +html_static_path = ['cpython/Doc/tools/static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = 'python' + release.replace('.', '') + +# Split the index +html_split_index = True + +# Relative filename of the reference count data file. +refcount_file = 'data/refcounts.dat' + + +os.system('ln -nfs `pwd` cpython/locales/es/LC_MESSAGES') diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000000..7cec904a1c --- /dev/null +++ b/requirements.txt @@ -0,0 +1,4 @@ +Sphinx==2.2.0 +setuptools +blurb +python-docs-theme From 98633b2a063c62c5c2899d86fa8ad09de831bfff Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 20:55:47 +0200 Subject: [PATCH 02/17] Path to conf.py --- .readthedocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index f8bfd6bd18..f333eb794b 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -7,7 +7,7 @@ version: 2 # Build documentation in the docs/ directory with Sphinx sphinx: - configuration: cpython/Doc/conf.py + configuration: conf.py # Optionally set the version of Python and requirements required to build your docs python: From 8a35ff3ba90460d4ad3b457b025d953476359117 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 20:57:43 +0200 Subject: [PATCH 03/17] Make version a string --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 715aa4788b..c2b0403ea6 100644 --- a/conf.py +++ b/conf.py @@ -12,7 +12,7 @@ project = 'Python en Español' copyright = '2001-%s, Python Software Foundation' % time.strftime('%Y') -release = version = 3.7 +release = version = '3.7' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: From 028a81e58e80ac73039d2dde9f56a8f2555ef1e7 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 21:20:54 +0200 Subject: [PATCH 04/17] Submodule 3.7 --- cpython | 1 + 1 file changed, 1 insertion(+) create mode 160000 cpython diff --git a/cpython b/cpython new file mode 160000 index 0000000000..48ef06b626 --- /dev/null +++ b/cpython @@ -0,0 +1 @@ +Subproject commit 48ef06b62682c19b7860dcf5d9d610e589a49840 From 9914c624639d3e2220273f2df3dd757ac058b297 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 21:25:48 +0200 Subject: [PATCH 05/17] Create locales directories --- conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/conf.py b/conf.py index c2b0403ea6..c75cd4445d 100644 --- a/conf.py +++ b/conf.py @@ -81,4 +81,5 @@ refcount_file = 'data/refcounts.dat' +os.system('mkdir -p cpython/locales/es/') os.system('ln -nfs `pwd` cpython/locales/es/LC_MESSAGES') From af6e79fda322dcff1ddb908b7d6010e0e31bceb1 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 21:25:57 +0200 Subject: [PATCH 06/17] How I do create the submodule pinned to a commit --- conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/conf.py b/conf.py index c75cd4445d..bc5e2f988a 100644 --- a/conf.py +++ b/conf.py @@ -1,3 +1,7 @@ +# Git Submodule +# https://stackoverflow.com/a/27445058 + + import sys, os, time sys.path.append(os.path.abspath('cpython/Doc/tools/extensions')) sys.path.append(os.path.abspath('cpython/Doc/includes')) From 582dfcfc899bbcda456f1e148a472bd03ceadc03 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 21:29:11 +0200 Subject: [PATCH 07/17] refcount data path --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index bc5e2f988a..6a83608c6d 100644 --- a/conf.py +++ b/conf.py @@ -82,7 +82,7 @@ html_split_index = True # Relative filename of the reference count data file. -refcount_file = 'data/refcounts.dat' +refcount_file = 'cpython/Doc/data/refcounts.dat' os.system('mkdir -p cpython/locales/es/') From 90e146beeed99c2cebe4fe1bf4525490361b9eae Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 21:59:28 +0200 Subject: [PATCH 08/17] Add some help to the conf.py file --- conf.py | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/conf.py b/conf.py index 6a83608c6d..76a82dda84 100644 --- a/conf.py +++ b/conf.py @@ -1,7 +1,15 @@ -# Git Submodule +# Sphinx configuration file. +# +# Most of the content of this file comes from cpython/Doc/conf.py +# It's modified to: +# - append the path considering the cpython submodule is at ./cpython +# - create the symbolic links under ./cpython/locale/es/LC_MESSAGES +# - make the build to work under Read the Docs +# +# The git submodule was created using this Stack Overflow answer +# to fetch only the commit that I needed and avoid clonning the whole history # https://stackoverflow.com/a/27445058 - import sys, os, time sys.path.append(os.path.abspath('cpython/Doc/tools/extensions')) sys.path.append(os.path.abspath('cpython/Doc/includes')) From e323a8fd0762c179d3c14e83a145b0919a6f16f5 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 22:09:33 +0200 Subject: [PATCH 09/17] Locale Sphinx configs --- conf.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/conf.py b/conf.py index 76a82dda84..d45aded14c 100644 --- a/conf.py +++ b/conf.py @@ -95,3 +95,7 @@ os.system('mkdir -p cpython/locales/es/') os.system('ln -nfs `pwd` cpython/locales/es/LC_MESSAGES') + + +gettext_compact = False +locale_dirs = ['cpython/locales'] From 68151c5900af84bc7a199f5b4b79dc00d1274663 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 22:42:58 +0200 Subject: [PATCH 10/17] Make the build to use the proper sourcedir --- conf.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index d45aded14c..3511a922af 100644 --- a/conf.py +++ b/conf.py @@ -90,7 +90,7 @@ html_split_index = True # Relative filename of the reference count data file. -refcount_file = 'cpython/Doc/data/refcounts.dat' +refcount_file = 'data/refcounts.dat' os.system('mkdir -p cpython/locales/es/') @@ -99,3 +99,8 @@ gettext_compact = False locale_dirs = ['cpython/locales'] + + +def setup(app): + # Change the sourcedir programmatically because Read the Docs always call it with `.` + app.srcdir = 'cpython/Doc' From 069fdfc3b8282c22e78cf3d2a49fb357c0f147c1 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Fri, 1 May 2020 23:59:42 +0200 Subject: [PATCH 11/17] Example of running with sphinx-build --- .gitignore | 1 + conf.py | 4 ++++ 2 files changed, 5 insertions(+) diff --git a/.gitignore b/.gitignore index cd1f2c9439..3398763c1c 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ *.mo +/_build/ diff --git a/conf.py b/conf.py index 3511a922af..f8e9b97d33 100644 --- a/conf.py +++ b/conf.py @@ -9,6 +9,10 @@ # The git submodule was created using this Stack Overflow answer # to fetch only the commit that I needed and avoid clonning the whole history # https://stackoverflow.com/a/27445058 +# +# This can be built locally using `sphinx-build` by running +# +# $ sphinx-build -b html -n -d _build/doctrees -D language=es . _build/html import sys, os, time sys.path.append(os.path.abspath('cpython/Doc/tools/extensions')) From bc125aacc6f734a24e9fa1d33a804231546019dd Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Sat, 2 May 2020 00:00:04 +0200 Subject: [PATCH 12/17] Correct Python version --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index f8e9b97d33..9c98b756c1 100644 --- a/conf.py +++ b/conf.py @@ -28,7 +28,7 @@ project = 'Python en Español' copyright = '2001-%s, Python Software Foundation' % time.strftime('%Y') -release = version = '3.7' +release = version = '3.7.7' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: From 782222430dd02b225bcd25dcfeb196b79f90ccbe Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Sat, 2 May 2020 00:00:11 +0200 Subject: [PATCH 13/17] Locale is relative to sourcedir --- conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/conf.py b/conf.py index 9c98b756c1..b698e222b1 100644 --- a/conf.py +++ b/conf.py @@ -100,9 +100,8 @@ os.system('mkdir -p cpython/locales/es/') os.system('ln -nfs `pwd` cpython/locales/es/LC_MESSAGES') - gettext_compact = False -locale_dirs = ['cpython/locales'] +locale_dirs = ['../locales'] # relative to the sourcedir def setup(app): From 6ad97e89e5aeee7a8c29f6af577ef08f6e7747c6 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Sat, 2 May 2020 00:12:23 +0200 Subject: [PATCH 14/17] Without this path the index is not translated --- conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/conf.py b/conf.py index b698e222b1..32bb401e11 100644 --- a/conf.py +++ b/conf.py @@ -101,7 +101,7 @@ os.system('ln -nfs `pwd` cpython/locales/es/LC_MESSAGES') gettext_compact = False -locale_dirs = ['../locales'] # relative to the sourcedir +locale_dirs = ['../locales', 'cpython/locales'] # relative to the sourcedir def setup(app): From 5dd76e90bfac1cc34fdbf5d77e53062e4974922f Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Sat, 2 May 2020 00:59:48 +0200 Subject: [PATCH 15/17] Reduce the overrides and re-use as much as possible --- conf.py | 75 +++------------------------------------------------------ 1 file changed, 4 insertions(+), 71 deletions(-) diff --git a/conf.py b/conf.py index 32bb401e11..9c052049a3 100644 --- a/conf.py +++ b/conf.py @@ -18,92 +18,25 @@ sys.path.append(os.path.abspath('cpython/Doc/tools/extensions')) sys.path.append(os.path.abspath('cpython/Doc/includes')) -# General configuration -# --------------------- - -extensions = ['sphinx.ext.coverage', 'sphinx.ext.doctest', - 'pyspecific', 'c_annotations', 'escape4chm'] +# Import all the Sphinx settings from cpython +sys.path.append(os.path.abspath('cpython/Doc')) +from conf import * +release = version = '3.7.7' project = 'Python en Español' copyright = '2001-%s, Python Software Foundation' % time.strftime('%Y') -release = version = '3.7.7' - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -today = '' -# Else, today_fmt is used as the format for a strftime call. -today_fmt = '%B %d, %Y' - -# By default, highlight as Python 3. -highlight_language = 'python3' - -# Minimum version of sphinx required -needs_sphinx = '1.8' - -# Ignore any .rst files in the venv/ directory. -exclude_patterns = ['venv/*', 'README.rst'] - -# Avoid a warning with Sphinx >= 2.0 -master_doc = 'contents' - -# Use our custom theme. -html_theme = 'python_docs_theme' html_theme_path = ['cpython/Doc/tools'] -html_theme_options = { - 'collapsiblesidebar': True, - 'issues_url': 'https://docs.python.org/3/bugs.html', - 'root_include_title': False # We use the version switcher instead. -} - -# Short title used e.g. for <title> HTML tags. -html_short_title = '%s Documentation' % release - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -html_last_updated_fmt = '%b %d, %Y' - -# Path to find HTML templates. templates_path = ['cpython/Doc/tools/templates'] - -# Custom sidebar templates, filenames relative to this file. -html_sidebars = { - # Defaults taken from http://www.sphinx-doc.org/en/stable/config.html#confval-html_sidebars - # Removes the quick search block - '**': ['localtoc.html', 'relations.html', 'customsourcelink.html'], - 'index': ['indexsidebar.html'], -} - -# Additional templates that should be rendered to pages. -html_additional_pages = { - 'download': 'download.html', - 'index': 'indexcontent.html', -} - -# Output an OpenSearch description file. -html_use_opensearch = 'https://docs.python.org/' + version - -# Additional static files. html_static_path = ['cpython/Doc/tools/static'] -# Output file base name for HTML help builder. -htmlhelp_basename = 'python' + release.replace('.', '') - -# Split the index -html_split_index = True - -# Relative filename of the reference count data file. -refcount_file = 'data/refcounts.dat' - - os.system('mkdir -p cpython/locales/es/') os.system('ln -nfs `pwd` cpython/locales/es/LC_MESSAGES') gettext_compact = False locale_dirs = ['../locales', 'cpython/locales'] # relative to the sourcedir - def setup(app): # Change the sourcedir programmatically because Read the Docs always call it with `.` app.srcdir = 'cpython/Doc' From 62b4db952758e8ee8aa49c2a2fd45062c18ecc66 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Sat, 2 May 2020 01:05:39 +0200 Subject: [PATCH 16/17] Small doc change --- conf.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/conf.py b/conf.py index 9c052049a3..b2481281ee 100644 --- a/conf.py +++ b/conf.py @@ -1,7 +1,6 @@ # Sphinx configuration file. # -# Most of the content of this file comes from cpython/Doc/conf.py -# It's modified to: +# - import original configurations from cpython/Doc/conf.py # - append the path considering the cpython submodule is at ./cpython # - create the symbolic links under ./cpython/locale/es/LC_MESSAGES # - make the build to work under Read the Docs From 309ef1f30556fc58776529461750af732765f4c5 Mon Sep 17 00:00:00 2001 From: Manuel Kaufmann <humitos@gmail.com> Date: Sat, 2 May 2020 01:15:15 +0200 Subject: [PATCH 17/17] version != release --- conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index b2481281ee..b5edfd203d 100644 --- a/conf.py +++ b/conf.py @@ -21,7 +21,8 @@ sys.path.append(os.path.abspath('cpython/Doc')) from conf import * -release = version = '3.7.7' +version = '3.7' +release = '3.7.7' project = 'Python en Español' copyright = '2001-%s, Python Software Foundation' % time.strftime('%Y')