From 67a1b63bfdbe9b96a56522097b3993b0cf76e511 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89tienne=20Mollier?= Date: Wed, 4 Jan 2023 22:36:31 +0100 Subject: [PATCH 1/3] Failure to produce documentation with python3.11. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In [Debian Bug#1027936], Adrian Bunk noticed that the documentation failed to be produced with python3.11 with the following symptom: Traceback (most recent call last): File "/usr/lib/python3/dist-packages/sphinx/config.py", line 350, in eval_config_file exec(code, namespace) File "/<>/docs_sphinx/conf.py", line 71, in generate_examples.main(root_dir, target_dir) File "/<>/debian/tmp/usr/lib/python3.11/dist-packages/brian2/sphinxext/generate_examples.py", line 72, in main with codecs.open(fname, 'rU', encoding='utf-8') as f: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ File "", line 906, in open ValueError: invalid mode: 'rUb' This patch removes a couple of uses of unified newline "open" invocations, which have no effect since the first version of python3. This may cause changes of behavior with python2, but this interpreter is unmaintained since 2020. [Debian Bug#1027936]: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=1027936 Signed-off-by: Étienne Mollier --- brian2/sphinxext/generate_examples.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/brian2/sphinxext/generate_examples.py b/brian2/sphinxext/generate_examples.py index 17a77d595..c7275cf4c 100644 --- a/brian2/sphinxext/generate_examples.py +++ b/brian2/sphinxext/generate_examples.py @@ -71,7 +71,7 @@ def main(rootpath, destdir): # We assume all files are encoded as UTF-8 examplescode = [] for fname in examplesfnames: - with codecs.open(fname, "rU", encoding="utf-8") as f: + with codecs.open(fname, "r", encoding="utf-8") as f: examplescode.append(f.read()) examplesdocs = [] examplesafterdoccode = [] @@ -168,7 +168,7 @@ def main(rootpath, destdir): relpath = "" full_name = relpath.replace("/", ".").replace("\\", ".") + "." + file + ".rst" category_additional_files[relpath].append((file, full_name)) - with codecs.open(fname, "rU", encoding="utf-8") as f: + with codecs.open(fname, "r", encoding="utf-8") as f: print(fname) content = f.read() output = file + "\n" + "=" * len(file) + "\n\n" From caa83df9bf13b02eedbc01a39c9211ba814dbe04 Mon Sep 17 00:00:00 2001 From: Marcel Stimberg Date: Thu, 5 Jan 2023 15:20:05 +0100 Subject: [PATCH 2/3] Replace codecs.open by open --- brian2/sphinxext/generate_examples.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/brian2/sphinxext/generate_examples.py b/brian2/sphinxext/generate_examples.py index c7275cf4c..a1ade32ec 100644 --- a/brian2/sphinxext/generate_examples.py +++ b/brian2/sphinxext/generate_examples.py @@ -1,4 +1,3 @@ -import codecs import fnmatch import glob import os @@ -71,7 +70,7 @@ def main(rootpath, destdir): # We assume all files are encoded as UTF-8 examplescode = [] for fname in examplesfnames: - with codecs.open(fname, "r", encoding="utf-8") as f: + with open(fname, encoding="utf-8") as f: examplescode.append(f.read()) examplesdocs = [] examplesafterdoccode = [] @@ -157,7 +156,7 @@ def main(rootpath, destdir): print("Found example image file", image) output += f".. image:: ../resources/examples_images/{image}\n\n" - with codecs.open(os.path.join(destdir, exname + ".rst"), "w", "utf-8") as f: + with open(os.path.join(destdir, exname + ".rst"), "w", encoding="utf-8") as f: f.write(output) category_additional_files = defaultdict(list) @@ -168,7 +167,7 @@ def main(rootpath, destdir): relpath = "" full_name = relpath.replace("/", ".").replace("\\", ".") + "." + file + ".rst" category_additional_files[relpath].append((file, full_name)) - with codecs.open(fname, "r", encoding="utf-8") as f: + with open(fname, encoding="utf-8") as f: print(fname) content = f.read() output = file + "\n" + "=" * len(file) + "\n\n" @@ -176,7 +175,7 @@ def main(rootpath, destdir): content_lines = ["\t" + l for l in content.split("\n")] output += "\n".join(content_lines) output += "\n\n" - with codecs.open(os.path.join(destdir, full_name), "w", "utf-8") as f: + with open(os.path.join(destdir, full_name), "w", encoding="utf-8") as f: f.write(output) mainpage_text = "Examples\n" From c442df5b684a9d816b3f901c1f25f6717e2e8c13 Mon Sep 17 00:00:00 2001 From: Marcel Stimberg Date: Thu, 5 Jan 2023 15:20:27 +0100 Subject: [PATCH 3/3] Test docs building in test suite --- .github/workflows/testsuite.yml | 37 +++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/.github/workflows/testsuite.yml b/.github/workflows/testsuite.yml index 1bf0fc905..864c9fd14 100644 --- a/.github/workflows/testsuite.yml +++ b/.github/workflows/testsuite.yml @@ -110,3 +110,40 @@ jobs: coveralls --finish env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + test_doc_build: + needs: get_python_versions + name: Test building the documentation + runs-on: ubuntu-latest + defaults: + run: + shell: bash -l {0} + steps: + - name: Checkout Repository + uses: actions/checkout@v2 + with: + fetch-depth: 0 + submodules: true + + - name: Setup Conda and Python + uses: conda-incubator/setup-miniconda@v2 + with: + auto-update-conda: true + auto-activate-base: false + channels: conda-forge,defaults + channel-priority: true + activate-environment: 'test_env' + python-version: "${{ needs.get_python_versions.outputs.max-python }}" + + - name: Install dependencies + run: pip install -r rtd-requirements.txt + + - name: Install brian2 + run: pip install . + + - name: Build HTML documentation + run: | + cd docs_sphinx + sphinx-build -b html . ../docs + env: + READTHEDOCS: True