Pypi Project Template

This project provides snippets for python library developers.

• GitLab CI Templates
  • Requirements
  • Usage
  • Docs Site
• Shared Configuration
• Auto Docstring Template

Template of gitlab.ci.yml for pypi package CI/CD.

1. pyproject.toml.
   • ci-templates/test.gitlab-ci.yml requires pytest, flake8.
   • ci-templates/docs.gitlab-ci.yml requires sphinx, sphinx-immaterial (for version dropdown).
2. python pre-installed in image (default image: python:3.7).
3. build, test, deploy stages. (included in default stages)
4. docs requires
   • $CI_PUSH_TOKEN environment variable.
   • docs/ generated by sphinx-quickstart docs --sep.
   • docs/build/html, public/ are RESERVED for generated docs.
   • pages branch is RESERVED for public pages.

poetry will be installed in script of each jobs.

Example .gitlab-ci.yml:

include:
  - project: 'DYSK_Labs/pypi-project-template'
    ref: master  # or other branch / commit / tag
    file:
      - ci-templates/test.gitlab-ci.yml
      - ci-templates/publish.gitlab-ci.yml
      - ci-templates/docs.gitlab-ci.yml

All jobs in templates extend corresponding hidden jobs with leading .. When override jobs, reference to the hidden one to avoid circular reference.

build:
  script:
    - echo "before"
    # !reference [build, script] causes circular reference
    - !reference [.build, script]
    - echo "after"

There's also a .snippet section to be reused.

test:
  script:
    - echo "before install poetry"
    - !reference [.snippet, install-poetry]
    ...

before_script & after_script are not defined by templates. Feel free to add commands like apt-get install.

The generated docs site will be served by GitLab Pages, located at https://dysk_labs.gitlab.io/${project_name}, check the demo site.

It's also included in test-docs job's artifact (only single version).

Don't forget to add version_dropdown to your conf.py:

extensions = [
    ...
    'sphinx_immaterial',
]
html_theme = 'sphinx_immaterial'
html_theme_options = {
    ...
    'version_dropdown': True,
}

Configuration includes flake8, isort & coverage.

nitpick

$ pip install nitpick

add the following section to your .nitpick.toml or pyproject.toml (detail)

[tool.nitpick]
style = [
    # don't forget to replace the <REF>
    "https://github.com/aetherAI/Pypi-Project-Template/blob/<REF>/nitpick-style/lint.toml",
    # ...,  optional, will override the former
    "https://github.com/aetherAI/Pypi-Project-Template/blob/<REF>/nitpick-style/coverage.toml",
]
cache = "never"

finally, run:

$ nitpick check -v
$ nitpick fix -v

Custom template file for VSCode extension Python Docstring Generator.

1. Add Custom Template Path

   

2. Generate docstring for function

   

3. Result of generation

   

4. Result of Pylance display