sveetch / cookiecutter-sveetch-python Goto Github PK

This is because the doc requirement file forgotten to add extra requirement name:

https://github.com/sveetch/cookiecutter-sveetch-python/blob/master/%7B%7Bcookiecutter.package_name%7D%7D/docs/requirements.txt#L1

It should be instead:

{{ cookiecutter.package_name }}[doc]

This has been seen on 'sveetch-python-sample' doc build failure, so it will need to be updated also to resolve documentation build.

Copy the new README structure from the djangoapp cookiecutter.

With Sphinx + RTD theme + livereload.

If possible, make it optional from cookie options so it can be removed from post hook alike:

https://github.com/audreyr/cookiecutter-pypackage/blob/master/hooks/post_gen_project.py

Currently, the requirement file in docs/ directory (that is used only by RTD in their building config) use the package extra dev requirement:

https://github.com/sveetch/cookiecutter-sveetch-python/blob/master/%7B%7Bcookiecutter.package_name%7D%7D/docs/requirements.txt#L1

This is wrong, because it force RTD to install application package to get dev requirement. Since the first RTD build job is to clone repository, it does not have any sense to use the package in the RTD building process because it does not reflect what could be in a new version from the repository (either master or any other branch).

Commonly this does not make troubles, but once there is build failure related to requirement or package, it make things really hard to debug.

Solution

• Assume documentation build is something out of package setup and remove "doc" extra requirements from setup.cfg;
• Move doc requirements directly in docs/requirements.txt;
• Update Makefile to include additional docs/requirements.txt after all package setup requirements;

It is used in clean-install command to remove the egg-info file.

But in a egg-info file name the character - is replace by _, which is not done in the package name created from the cookiecutter.

New variable PACKAGE_SLUG=echo $(PACKAGE_NAME) | tr '-' '_'`` should be added and used in clean-install instead of `PACKAGE_NAME`.

From documentation: https://sveetch-python-sample.readthedocs.io/en/latest/cli.html usage examples assume the package is installed in a virtual environment, but that is not the basic way to install it as described in Install document.

It should just remove everything about virtual env and possibly describe the virtual env way in Development document instead.

Since pyproject.toml have been largely adopted since the introduction in a PEP, this is time to move, even setuptools now is starting to warn about setup.cfg, so there is no more a real choice.

The TOML config file is the official new way to go since it has been validated in a PEP. However it seems not totally ready yet because of some very common packages having troubles with it:

• It makes PIP to enter in isolation mode : https://pip.pypa.io/en/stable/reference/build-system/pyproject-toml/ which has been criticized, honestly i don't see all the scope of this problems for now;
• Flake8 does not support it to hold its configuration so we still need to have a setup.cfg or a .flake8 file

There is a summary of common packaging tools that does not support yet the TOML config:

https://github.com/flying-sheep/awesome-python-packaging

In opposite, there is a few package now that does not support setup.cfg or even their proprietary config file like .flake8. Black is one these package, it only supports for TOML configuration and nothing else, which currently would requires to have a pyproject.toml to hold its configuration.

The benefits of TOML files are just not enough yet to migrate to it, this issue will still remain opened until Python ecosystem has resolved it, especially Flake and PIP.

Other useful discussion links related to this subject:

• https://discuss.python.org/t/pip-pyproject-toml-and-debug-builds/3766/1 Where some tips has been given for pip and isolation workaround;
• PyCQA/flake8#234 The Flake8 issue awaiting for a resolution to implement support of TOML config;
• psf/black#683 The Black issue that definitively closed door to any other support than TOML config;

This should be something like this in a setup.py:

    project_urls={
        "Changelog": "https://github.com/THE_REPO/THE_PACKAGE/blob/main/CHANGELOG.rst",
        "Issue Tracker": "https://github.com/THE_REPO/THE_PACKAGE/issues",
        "Discussions": "https://github.com/THE_REPO/THE_PACKAGE/discussions",
        "Documentation": "https://THE_PACKAGE.readthedocs.io/",
    },

But to adapt to setup.cfg or pyproject.toml format (depending adopted pkg configuration at the moment of working on this issue)

With a scope "function" it allow to create an unique temp dir for each parameterizer

The encoding file start is deprecated:

# -*- coding: utf-8 -*-

It's useless since Python3, only for Python2 that is out of scope now. Remove this from every modules.

Todo cookie

• Use private setting like _cookie_sveetch_python_version in cookiecutter.json to write the current cookie version
• Add make project to build in dist/
• Add cookiebaked.json ?

Todo template

• #12
• #11
• #9
• Upgrade application __init__.py to the modern way to load version;
• Upgrade documentation to a new theme, improved sphinx_reload script and move it into docs/
• Improve Makefile (suffix bin path variables with _BIN and add missing var PYTHON_BIN)
• Include README in docs/index instead of duplicating it
• Don't test all supported Python version in tox config, only the min and max
• Split extra requirements into various accurate extra spaces (dev, quality, release, etc..) to avoid making Tox installing useless stuff (like Flake8) for testing;
• Flake task should be something like $(FLAKE_BIN) --statistics --show-source $(APPLICATION_NAME) tests (add statistics and use a single job for app and tests lint)

Finally

• Update repository sample with 0.4.0

With arguments for "name", format (plain or html) and possible "container" (only for html).

Then test it.

This is a forgotten path from a development sample, adding_doc should be instead a Jinja variable to the root module.

According to https://packaging.python.org/en/latest/specifications/core-metadata/#core-metadata-keywords , currently the cookie make a setup with keyword separated with spaces, it should be fixed.

Shipped logging helper "init_logger" is not used in code or tests.