Generate this doc as html so the links works by issuing:

rst2html.py  --traceback  release_checklist_details.txt > release_checklist_details.html

in a venv with doctutils installed.

Start

Test part1

While doing this keep notes about discoveries in python and libs versions required, they will be handy to update documentation.

At least the combinations of (py_min, py_max) x (pyglet_min, pyglet_max), with special attention to (py_max, pyglet_max) should be tested.

Use cocos-testcmp to run the unittests and compare snapshots with a know good reference.

For each python version supported, or at least py_min, py_max, do

Test, part two

Scripts outside test/ should be tested, meaning manual run and eyeballing they look good Fix any discovered issue. Code fixes that touch cocos/ must uncheck the 'Test, part one', and all Test, part two

Build docs first pass

Fill boilerplate release data

Packaging round1

Final docs pass

Final build

Upload to pypi

Final Tasks

Notes

(Write here things discovered that may need further actions)


Details

Create and use venvs

Details may vary by OS and shell, you can lookup details in the Python's docs for module venv.

  • example windows in a 'cmd.exe' shell / console
    • create:

      >py -3.7 -m venv venv_directory
      

      Creates a venv_directory and sets there the files needed

    • activate:

      >venv_directory\Scripts\activate
      

      When the venv is active, the command 'python' will invoke the python in venv

    • deactivate:

      >deactivate
      
    • while the venv is activated, in that console
      • venv_directoryScripts will be in the path, handy for commands like 'pytest', 'rst2html.py' and other provided by packages installed in the venv
      • commands '*.py' issued in the venv console will be executed by the python in the venv, good for commands like 'rst2html.py'
  • example linux (raspbian) in a 'bash' shell / console
    • create:

      $ python -m venv venv_directory
      

      Creates a venv_directory and sets there the files needed

    • activate:

      $ source venv_directory/Scripts/activate
      

      When the venv is active, the command 'python' will invoke the python in venv

    • deactivate:

      $ deactivate
      
    • while the venv is activated, in that console
      • venv_directory/Scripts will be in the path, handy for commands like 'pytest', 'rst2html.py' and other provided by packages installed in the venv
      • commands '*.py' issued in the venv console will be executed by the python in the venv, good for commands like 'rst2html.py'
    • venvdir/Scripts/python will run the python in the venv, meaning imports will give modules and packages installed in that venv, even if the environmet is not activated

Using pip

  • First of all upgrade pip to last version:

    python -m pip install pip --upgrade
    
  • Installing from pypi

    Some packages have a pypi name different from the import name, by example pypi name 'pillow' uses 'PIL' to import, or pypi name 'cocos2d' uses import name 'cocos'. The pip command needs the pypi name.

    The pypi name can be given version restrictions, and at least in windows when the version restriction includes a '>' or a '<' you must use quotes so the shell don't take as a redirect. Quoting is done with double quotes in windows, single in linux.

    Examples, you must use the quote character appropriate to your shell:

    python -m pip install pillow
    python -m pip install 'pillow<8'
    python -m pip install "pyglet==1.4.11"
    python -m pip install 'pyglet<2,>1.4.10'
    
  • Installing from a local package archive

    A package built with sdist build ... will produce a file <pkg_name>.[zip | tar.gz | whl]

    To install from that file, use:

    python -m pip install filename
    
  • Installing in developer mode

    If dir_z has a setup.py file, then running the command:

    python -m pip install -e dir_z
    

    will install the package and dependencies described on the setup.py

    This is a common style to install from a DVCS (git, etc) clone

Using cocos-testcmp

This app lives at https://github.com/los-cocos/cocos-testcmp

Instructions to run in cocos-testcmp's Readme

Build docs details

  • Last build (2023) installed markupsafe==2.0.1, jinja2==2.11.2, sphinx==3.2.0 (in that order)

  • set the SPHINXDIR environment to the (venv dir)/Scripts

  • cd docgen

  • to clean, make clean in Windows, makefile clean in linux

  • to build, make html in Windows, makefile html in linux

  • the build will create a log with warnings and errors, docgen/warnings.log

  • some warnings are expected, in windows without sdl installed the build ends with 24 warnings:

    WARNING: while setting up extension sphinx.addnodes: node class 'meta' is already registered, its visitors will be overridden
    WARNING: html_static_path entry '_static' does not exist
    WARNING: missing attribute mentioned in :members: or __all__: module cocos.audio, attribute SDL
    WARNING: missing attribute mentioned in :members: or __all__: module cocos.audio, attribute pygame
    WARNING: autodoc: failed to import module 'SDL' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.array' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.audio' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.constants' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.darwin' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.dll' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.endian' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.error' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.mixer' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.rwops' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.sound' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.timer' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'SDL.version' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'pygame' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'pygame.base' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'pygame.mixer' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'pygame.music' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    WARNING: autodoc: failed to import module 'pygame.version' from module 'cocos.audio'; the following exception was raised:
    Dynamic library "SDL" was not found
    D:\dev\cocos2020\docgen\api\modules.txt: WARNING: document isn't included in any toctree
    D:\dev\cocos2020\docgen\euclid.txt: WARNING: document isn't included in any toctree
    
  • To start navigating the docs, open docgen_buildhtmlindex.html in a browser

Check a file is reST compatible

In the venv where Sphix was installed do a:

rst2html.py --traceback file >out.html

Fix any traceback appearing, open the .html in a browser, even if they are no warnings, and see if the view is the desired one.

Details upload to pypi

In the activated venv used ro build the package, at the root of Working Directory used ro build the package:

pip install twine
twine upload -u user -p pwd dist/*

Obviously use your pypi user and pwd