Repository: openfisca/openfisca-core (language: python)

Issue:
Fix doc test & build dependency errors
Fixes #1136
Fixes #1140

#### Technical changes

- Fix `pycodestyle` dependency in fresh editable installations.
- Fix `flake8` dependency in fresh editable installations.

Note: this PR is the continuation of #1137, but seems the solution was not complete. This PR should unblock doc tests failing because of dependency mismatch.



Discussion / hints:

[![Coverage Status](https://coveralls.io/builds/51291846/badge)](https://coveralls.io/builds/51291846)

Coverage remained the same at 78.94% when pulling **3a026fb75b1ae7fd025bbe80bbd4e816ef7bc8a9 on fix-pristine-editable-install** into **e18f23be34b5964e89ee65e33669da1a0996ee73 on master**.

As described in https://github.com/openfisca/openfisca-core/issues/1140#issuecomment-1200902579, I believe there is no way we currently can reproduce the documented failure, so we cannot know if publishing this version will fix the problem. I was trustful for #1137, but I cannot approve this PR under these circumstances now, especially considering that it currently reverts #1137 yet introduces other untestable dependency changes.

I would fast approve a pure #1137 revert, considering that the issue #1136 it fixed was extremely minor (misleading log with no consequence), or could consider approving this if #1140 included a repeatable procedure for testing changes. I would also ask that the `1> /dev/null` silencers in the `test-doc-install` step are removed so we can follow better what is happening.
> I would like us to understand the reason why the tests passed in #1137 and failed afterwards on `master`. What differs? Until we understand this, all fixes are bound to be uncertain. We cannot iterate on production versions by publishing a new patch every day.

Yes, it's a revert / and could also be handled as such TBH. I gave some hours to try to understand the issue, and gave up by reverting that specific lib upgrade after taking a closer look at the errors.

IMHO the ideal way of being able to catch this sooner is to include doc dependencies in in openfisca-core (for example _.[doc]_). 

It's a trade-off, certainly.
> As described in [#1140 (comment)](https://github.com/openfisca/openfisca-core/issues/1140#issuecomment-1200902579), I believe there is no way we currently can reproduce the documented failure, so we cannot know if publishing this version will fix the problem. I was trustful for #1137, but I cannot approve this PR under these circumstances now, especially considering that it currently reverts #1137 yet introduces other untestable dependency changes.
> 
> I would fast approve a pure #1137 revert, considering that the issue #1136 it fixed was extremely minor (misleading log with no consequence), or could consider approving this if #1140 included a repeatable procedure for testing changes. I would also ask that the `1> /dev/null` silencers in the `test-doc-install` step are removed so we can follow better what is happening.

Actually the `flake8` upgrade is a knight unrelated to the fix.
Fantastic, so what I get now:

```
flake8.exceptions.FailedToLoadPlugin: Flake8 failed to load plugin "pycodestyle.missing_whitespace_after_import_keyword" due to module 'pycodestyle' has no attribute 'missing_whitespace_after_import_keyword'.
```

So this is a layer 8 error: instead of downgrading pycodestyle, I proposed upgrading flask8. 

It concurred with the silencing and we got no clue of what was happing.

Let's remove the silencers!
Now by suppressing the silencers we have actionable logs:

```
The conflict is caused by:
    sphinx 4.5.0 depends on importlib-metadata>=4.4; python_version < "3.10"
    flake8 4.0.1 depends on importlib-metadata<4.3; python_version < "3.8"
    sphinx 4.5.0 depends on importlib-metadata>=4.4; python_version < "3.10"
    flake8 4.0.0 depends on importlib-metadata<4.3; python_version < "3.8"
```

https://github.com/openfisca/openfisca-core/runs/7611320470?check_suite_focus=true

Which confirms the need to rollback that upgrade.

Rollback or no, 

> Or could consider approving this if https://github.com/openfisca/openfisca-core/issues/1140 included a repeatable procedure for testing changes. I would also ask that the 1> /dev/null silencers in the test-doc-install step are removed so we can follow better what is happening.

I think this PR now provides an increase in our understanding of what's going on.
As I put it in the last commit:

_Versions >= 4.0.0 of flake8 require a library version, for clients using
Python < 3,8, that is incompatible with the same library requirement by
Sphinx >= 4.5._ 

Fix patch:
diff --git a/.github/workflows/workflow.yml b/.github/workflows/workflow.yml
index 6ffa9fa23b..fbb184954d 100644
--- a/.github/workflows/workflow.yml
+++ b/.github/workflows/workflow.yml
@@ -120,36 +120,6 @@ jobs:
       - name: Check NumPy typing against latest 3 minor versions
         run: for i in {1..3}; do VERSION=$(${GITHUB_WORKSPACE}/.github/get-numpy-version.py prev) && pip install numpy==$VERSION && make check-types; done
 
-  test-docs:
-    runs-on: ubuntu-latest
-    needs: [ build ]
-    env:
-      TERM: xterm-256color
-    steps:
-      - uses: actions/checkout@v2
-      - name: Checkout docs
-        run: make test-doc-checkout branch=${GITHUB_REF#refs/heads/}
-      - name: Set up Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: 3.7.12
-      - name: Cache build
-        id: restore-build
-        uses: actions/cache@v2
-        with:
-          path: ${{ env.pythonLocation }}
-          key: build-${{ env.pythonLocation }}-${{ hashFiles('setup.py') }}-${{ github.sha }}
-      - name: Cache docs
-        id: restore-docs
-        uses: actions/cache@v2
-        with:
-          path: ${{ env.pythonLocation }}
-          key: docs-${{ env.pythonLocation }}-${{ hashFiles('doc/requirements.txt') }}--${{ github.sha }}
-      - name: Install dependencies
-        run: make test-doc-install
-      - name: Run doc tests
-        run: make test-doc-build
-
   lint-files:
     runs-on: ubuntu-latest
     needs: [ build ]
@@ -174,7 +144,7 @@ jobs:
 
   check-version:
     runs-on: ubuntu-latest
-    needs: [ test-core, test-country-template, test-extension-template, check-numpy, test-docs, lint-files ] # Last job to run
+    needs: [ test-core, test-country-template, test-extension-template, check-numpy, lint-files ] # Last job to run
     steps:
       - uses: actions/checkout@v2
         with:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1b796fd3c0..4c0f1c293b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+### 35.8.6 [#1145](https://github.com/openfisca/openfisca-core/pull/1145)
+
+#### Technical changes
+
+- Removes the automatic documentation build check
+  - It has been proven difficult to maintain, specifically due _dependency hell_ and a very contrived build workflow.
+
 ### 35.8.5 [#1137](https://github.com/openfisca/openfisca-core/pull/1137)
 
 #### Technical changes
diff --git a/Makefile b/Makefile
index b5c73a5ff8..6ace90d5f5 100644
--- a/Makefile
+++ b/Makefile
@@ -3,7 +3,6 @@ include openfisca_tasks/lint.mk
 include openfisca_tasks/publish.mk
 include openfisca_tasks/serve.mk
 include openfisca_tasks/test_code.mk
-include openfisca_tasks/test_doc.mk
 
 ## To share info with the user, but no action is needed.
 print_info = $$(tput setaf 6)[i]$$(tput sgr0)
diff --git a/README.md b/README.md
index 2421c96ed2..d25506609b 100644
--- a/README.md
+++ b/README.md
@@ -135,70 +135,6 @@ OpenFisca’s toolchain checks whether documentation builds correctly and update
 
 In the meantime, please take a look at our [contributing guidelines](CONTRIBUTING.md) for some general tips on how to document your contributions, and at our official documentation's [repository](https://github.com/openfisca/openfisca-doc/blob/master/README.md) to in case you want to know how to build it by yourself —and improve it!
 
-### To verify that the documentation still builds correctly
-
-You can run:
-
-```sh
-make test-doc
-```
-
-### If it doesn't, or if the doc is already broken.
-
-Here's how you can fix it:
-
-1. Clone the documentation, if not yet done:
-
-```
-make test-doc-checkout
-```
-
-2. Install the documentation's dependencies, if not yet done:
-
-```
-make test-doc-install
-```
-
-3. Create a branch, both in core and in the doc, to correct the problems:
-
-```
-git checkout -b fix-doc
-sh -c "cd doc && git checkout -b `git branch --show-current`"
-```
-
-4. Fix the offending problems —they could be in core, in the doc, or both.
-
-You can test-drive your fixes by checking that each change works as expected:
-
-```
-make test-doc-build branch=`git branch --show-current`
-```
-
-5. Commit at each step, so you don't accidentally lose your progress:
-
-```
-git add -A && git commit -m "Fix outdated argument for Entity"
-sh -c "cd doc && git add -A && git commit -m \"Fix outdated argument for Entity\""
-```
-
-6. Once you're done, push your changes and cleanup:
-
-```
-git push origin `git branch --show-current`
-sh -c "cd doc && git push origin `git branch --show-current`"
-rm -rf doc
-```
-
-7. Finally, open a pull request both in [core](https://github.com/openfisca/openfisca-core/compare/master...fix-doc) and in the [doc](https://github.com/openfisca/openfisca-doc/compare/master...fix-doc).
-
-Continuous integration will automatically try to build the documentation from the same branch in both core and the doc (in our example "fix-doc") so we can integrate first our changes to Core, and then our changes to the doc.
-
-If no changes were needed to the doc, then your changes to core will be verified against the production version of the doc.
-
-If your changes concern only the doc, please take a look at the doc's [README](https://github.com/openfisca/openfisca-doc/blob/master/README.md).
-
-That's it! 🙌
-
 ## Serving the API
 
 OpenFisca-Core provides a Web-API. It is by default served on the `5000` port.
diff --git a/openfisca_tasks/install.mk b/openfisca_tasks/install.mk
index 57a9d65e5a..79f3938e44 100644
--- a/openfisca_tasks/install.mk
+++ b/openfisca_tasks/install.mk
@@ -2,7 +2,7 @@
 install:
 	@$(call print_help,$@:)
 	@pip install --upgrade pip twine wheel
-	@pip install --editable ".[dev]" --upgrade --use-deprecated=legacy-resolver
+	@pip install --editable ".[dev]" --upgrade
 
 ## Uninstall project dependencies.
 uninstall:
diff --git a/setup.py b/setup.py
index ceb3bcfda0..dfc9fcace5 100644
--- a/setup.py
+++ b/setup.py
@@ -42,12 +42,13 @@
     'mypy == 0.910',
     'openfisca-country-template >= 3.10.0, < 4.0.0',
     'openfisca-extension-template >= 1.2.0rc0, < 2.0.0',
+    'pycodestyle >= 2.8.0, < 2.9.0',
     'pylint == 2.10.2',
     ] + api_requirements
 
 setup(
     name = 'OpenFisca-Core',
-    version = '35.8.5',
+    version = '35.8.6',
     author = 'OpenFisca Team',
     author_email = 'contact@openfisca.org',
     classifiers = [


Test patch:
diff --git a/openfisca_tasks/test_doc.mk b/openfisca_tasks/test_doc.mk
deleted file mode 100644
index 2909b076b5..0000000000
--- a/openfisca_tasks/test_doc.mk
+++ /dev/null
@@ -1,78 +0,0 @@
-## The repository of the documentation.
-repo = https://github.com/openfisca/openfisca-doc
-
-## The current working branch.
-branch = $(shell git branch --show-current)
-
-## Check that the current changes do not break the doc.
-test-doc:
-	@##	Usage:
-	@##
-	@##		make test-doc [branch=BRANCH]
-	@##
-	@##	Examples:
-	@##
-	@##		# Will check the current branch in openfisca-doc.
-	@##		make test-doc
-	@##
-	@##		# Will check "test-doc" in openfisca-doc.
-	@##		make test-doc branch=test-doc
-	@##
-	@##		# Will check "master" if "asdf1234" does not exist.
-	@##		make test-doc branch=asdf1234
-	@##
-	@$(call print_help,$@:)
-	@${MAKE} test-doc-checkout
-	@${MAKE} test-doc-install
-	@${MAKE} test-doc-build
-	@$(call print_pass,$@:)
-
-## Update the local copy of the doc.
-test-doc-checkout:
-	@$(call print_help,$@:)
-	@[ ! -d doc ] && git clone ${repo} doc || :
-	@cd doc && { \
-		git reset --hard ; \
-		git fetch --all ; \
-		[ "$$(git branch --show-current)" != "master" ] && git checkout master || : ; \
-		[ "${branch}" != "master" ] \
-			&& { \
-				{ \
-					>&2 echo "$(print_info) Trying to checkout the branch 'openfisca-doc/${branch}'..." ; \
-					git branch -D ${branch} 2> /dev/null ; \
-					git checkout ${branch} 2> /dev/null ; \
-				} \
-					&& git pull --ff-only origin ${branch} \
-					|| { \
-						>&2 echo "$(print_warn) The branch 'openfisca-doc/${branch}' was not found, falling back to 'openfisca-doc/master'..." ; \
-						>&2 echo "" ; \
-						>&2 echo "$(print_info) This is perfectly normal, one of two things can ensue:" ; \
-						>&2 echo "$(print_info)" ; \
-						>&2 echo "$(print_info) $$(tput setaf 2)[If tests pass]$$(tput sgr0)" ; \
-						>&2 echo "$(print_info)     * No further action required on your side..." ; \
-						>&2 echo "$(print_info)" ; \
-						>&2 echo "$(print_info) $$(tput setaf 1)[If tests fail]$$(tput sgr0)" ; \
-						>&2 echo "$(print_info)     * Create the branch '${branch}' in 'openfisca-doc'... " ; \
-						>&2 echo "$(print_info)     * Push your fixes..." ; \
-						>&2 echo "$(print_info)     * Run 'make test-doc' again..." ; \
-						>&2 echo "" ; \
-						>&2 echo "$(print_work) Checking out 'openfisca-doc/master'..." ; \
-						git pull --ff-only origin master ; \
-					} \
-			} \
-			|| git pull --ff-only origin master ; \
-	} 1> /dev/null
-	@$(call print_pass,$@:)
-
-## Install doc dependencies.
-test-doc-install:
-	@$(call print_help,$@:)
-	@pip install --requirement doc/requirements.txt 1> /dev/null
-	@pip install --editable .[dev] --upgrade 1> /dev/null
-	@$(call print_pass,$@:)
-
-## Dry-build the doc.
-test-doc-build:
-	@$(call print_help,$@:)
-	@sphinx-build -M dummy doc/source doc/build -n -q
-	@$(call print_pass,$@:)