diff --git a/README.rst b/README.rst index be12f94..ca05a8c 100644 --- a/README.rst +++ b/README.rst @@ -80,21 +80,21 @@ Due to the development nature of cookiecutter, there are some limitations when u Cookiecutter Installation -------------------------- -The Python enviornment can be tricky sometimes in Windows. Use this documentation page for steps and tips on Windows installation: `Cookiecutter Installation - Windows `_ +The Python environment can be tricky sometimes in Windows. Use this documentation page for steps and tips on Windows installation: `Cookiecutter Installation - Windows `_ .py & /examples/_simpletest.py File Generation ------------------------------------------------------------------ -Cookiecutter was developed for use in \*\nix/OSX enviornments. When implementing prompt based configuration for things like filenames, special characters were used for programmatic detection and formatting. +Cookiecutter was developed for use in \*nix/OSX environments. When implementing prompt-based configuration for things like filenames, special characters were used for programmatic detection and formatting. .. code-block:: {% if cookiecutter.library_prefix %}{{ cookiecutter.library_prefix | lower }}_{% endif %}{{ cookiecutter.library_name | lower }}.py -As such, Windows will block the use of these special characters in filenames. So when cookiecutter pulls the Adafruit CircuitPython template, the .py and /examples/_simpletest.py files are not created. This adds an extra step. Simply copy an existing library's .py files (and structure if making a "package"), and change the prompted values (e.g. author name, library name, documentation information, etc). +As such, Windows will block the use of these special characters in filenames. So when cookiecutter pulls the Adafruit CircuitPython template, the .py and /examples/_simpletest.py files are not created. This adds an extra step. Simply copy an existing library's .py files (and structure if making a "package"), and change the prompted values (e.g. author name, library name, documentation information, etc). .. note:: - The above is from experience with using cookiecutter within a Windows native setup. This may not be applicable when using Windows Subsystem for Linux (WSL) or any *nix-For-Windows utilities. + The above is from experience with using cookiecutter within a Windows native setup. This may not be applicable when using Windows Subsystem for Linux (WSL) or any *nix-for-Windows utilities. - We are always exploring ways to make things easier, so this workflow may change. Also, ideas and solutions are always welcome! + We are always exploring ways to make things easier, so this workflow may change. Also, ideas and solutions are always welcome! \ No newline at end of file diff --git a/README.rst.bak.20260318032052 b/README.rst.bak.20260318032052 new file mode 100644 index 0000000..be12f94 --- /dev/null +++ b/README.rst.bak.20260318032052 @@ -0,0 +1,100 @@ +Introduction +============ + +.. image :: https://img.shields.io/discord/327254708534116352.svg + :target: https://adafru.it/discord + :alt: Discord + +This cookiecutter creates a project structure for an Adafruit CircuitPython library. + +See this Adafruit Learn Guide for an explanation of creating a CircuitPython library: `Creating and sharing a CircuitPython library `_ The section for using cookiecutter is `here `_. + +.. note:: + + The above Learn Guide is directed towards creating a library for the Community Bundle. For libraries meant for the Adafruit Bundle, contact the CircuitPython Helpers (@circuitpython helpers) on Discord or put in a new issue on the Adafruit_CircuitPython_Bundle GitHub repository. + +Cookiecutter Usage +=================== + +.. code-block:: bash + + # The first time + pip install cookiecutter~=2.1 + + cookiecutter gh:adafruit/cookiecutter-adafruit-circuitpython + +Then, fill in the prompts and accomplish some post generation cleanup: + +Prompts +-------- + +* ``target_bundle`` - Adafruit bundle or Community library bundle +* ``github_user`` - GitHub user or organization which will host this repo. For example, Adafruit funded libraries should say "adafruit" here. +* ``author_name`` - Who you are! Sets the copyright to you. +* ``company`` - Used to give Copyright credit to the company funding the library. For example, Adafruit funded libraries should say "Adafruit Industries" here. +* ``library_name`` - Shortest name for the library. Usually a chip name such as LIS3DH. +* ``library_description`` - Write a sentence describing the purpose of this library (e.g. ``CircuitPython helper library for the DC & Stepper Motor FeatherWing, Shield and Pi Hat kits.``). +* ``library_keywords`` - Used to populate keywords for PyPi. Enter a string of keywords (e.g ``dht temp humidity``) NOTE: The following are included by default: ``adafruit``, ``blinka``, ``circuitpython``, ``micropython``, and the ``library_name`` you enter. +* ``library_prefix`` - Used to prefix the code to the organization creating the library. For example, Adafruit supported libraries should say "adafruit" here. Do not add a - or _. +* ``adafruit_product_id`` - The product ID for the Adafruit product includes a link to the product in the README. Only applies to Adafruit Bundle. +* ``requires_bus_device`` - Determines whether to add comments about a dependency on `BusDevice `_. + If the library uses BusDevice, enter ``y`` or ``yes`` to include. If the library doesn't use BusDevice, all other entries including empty, will not include BusDevice. +* ``requires_register`` - Determines whether to add comments about a dependency on `Register `_. + If the library uses Register, enter ``y`` or ``yes`` to include. If the library doesn't use Register, all other entries including empty, will not include Register. +* ``other_requirements`` - Adds any other module dependencies for PyPi. Enter a comma separated string of modules + (e.g. ``adafruit-circuitpython-pca9685, adafruit-circuitpython-motor``). NOTE: ``Adafruit-Blinka`` is always included, so no need to include it here. +* ``sphinx_docs`` - Should the Sphinx based documentation be included in your repo? If so, enter ``y`` or ``yes`` to include the setup.py. For Adafruit libraries this defaults to Yes. + + +Post Generation Cleanup +------------------------ + +After generation, make sure to glance over the files to make sure they +autogenerated as you expect (such as capitalization). There are a few places +with ``.. todo::`` that should also be taken care of. After adding or updating +the information requested, make sure the ``.. todo::`` text is removed. Like this: + +.. code:: + + # Before Cleanup + .. todo:: Describe what the module does + +.. code:: + + # After Cleanup + This library talks to the AM4Z-1NG sensor. Typical use is for robot friends. + +.. note:: + + If you are not uploading the repository for Adafruit (i.e., the Community bundle), and you + wish to use the Release feature on GitHub to upload libraries to PyPI, you will need to + add your PyPI token to the repository secrets. Set a secret named ``PYPI_USERNAME`` to + ``__token__`` and a secret named ``PYPI_PASSWORD`` to your API token with the proper scope. + Never share your API token anyone! + +Windows Users +============== + +Due to the development nature of cookiecutter, there are some limitations when using with Windows. + +Cookiecutter Installation +-------------------------- + +The Python enviornment can be tricky sometimes in Windows. Use this documentation page for steps and tips on Windows installation: `Cookiecutter Installation - Windows `_ + + +.py & /examples/_simpletest.py File Generation +------------------------------------------------------------------ + +Cookiecutter was developed for use in \*\nix/OSX enviornments. When implementing prompt based configuration for things like filenames, special characters were used for programmatic detection and formatting. + +.. code-block:: + + {% if cookiecutter.library_prefix %}{{ cookiecutter.library_prefix | lower }}_{% endif %}{{ cookiecutter.library_name | lower }}.py + +As such, Windows will block the use of these special characters in filenames. So when cookiecutter pulls the Adafruit CircuitPython template, the .py and /examples/_simpletest.py files are not created. This adds an extra step. Simply copy an existing library's .py files (and structure if making a "package"), and change the prompted values (e.g. author name, library name, documentation information, etc). + +.. note:: + The above is from experience with using cookiecutter within a Windows native setup. This may not be applicable when using Windows Subsystem for Linux (WSL) or any *nix-For-Windows utilities. + + We are always exploring ways to make things easier, so this workflow may change. Also, ideas and solutions are always welcome! diff --git a/conf.py b/conf.py index e0747f6..d3a8736 100755 --- a/conf.py +++ b/conf.py @@ -22,7 +22,8 @@ # import os import sys -sys.path.insert(0, os.path.abspath('.')) + +sys.path.insert(0, os.path.abspath(".")) # -- General configuration ------------------------------------------------ @@ -34,40 +35,40 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.intersphinx', - 'sphinx.ext.viewcode', + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", ] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] +templates_path = ["_templates"] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = '.rst' +source_suffix = ".rst" # The encoding of source files. # # source_encoding = 'utf-8-sig' # The master toctree document. -master_doc = 'README' +master_doc = "README" # General information about the project. -project = u'Adafruit MCP9808 Library' -copyright = u'2017 Scott Shawcroft' -author = u'Scott Shawcroft' +project = "Adafruit MCP9808 Library" +copyright = "2017 Scott Shawcroft" +author = "Scott Shawcroft" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. -version = u'1.0' +version = "1.0" # The full version, including alpha/beta/rc tags. -release = u'1.0' +release = "1.0" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -88,7 +89,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # The reST default role (used for this markup: `text`) to use for all # documents. @@ -110,7 +111,7 @@ # show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] @@ -127,18 +128,19 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' +on_rtd = os.environ.get("READTHEDOCS", None) == "True" if not on_rtd: # only import and set the theme if we're building docs locally try: import sphinx_rtd_theme - html_theme = 'sphinx_rtd_theme' - html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.'] + + html_theme = "sphinx_rtd_theme" + html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), "."] except: - html_theme = 'default' - html_theme_path = ['.'] + html_theme = "default" + html_theme_path = ["."] else: - html_theme_path = ['.'] + html_theme_path = ["."] # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -172,7 +174,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -216,10 +218,6 @@ # # html_show_sourcelink = True -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# -# html_show_sphinx = True - # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. # # html_show_copyright = True @@ -252,109 +250,25 @@ # html_search_scorer = 'scorer.js' # Output file base name for HTML help builder. -htmlhelp_basename = 'AdafruitMCP9808Librarydoc' +htmlhelp_basename = "AdafruitMCP9808Librarydoc" # -- Options for LaTeX output --------------------------------------------- latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'AdafruitMCP9808Library.tex', u'Adafruit MCP9808 Library Documentation', - u'Phiilip Moyer', 'manual'), -] - -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# -# latex_use_parts = False - -# If true, show page references after internal links. -# -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# -# latex_appendices = [] - -# It false, will not define \strong, \code, itleref, \crossref ... but only -# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added -# packages. -# -# latex_keep_old_macro_names = True - -# If false, no module index is generated. -# -# latex_domain_indices = True - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'adafruitMCP9808library', u'Adafruit MCP9808 Library Documentation', - [author], 1) -] - -# If true, show URL addresses after external links. -# -# man_show_urls = False - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'AdafruitMCP9808Library', u'Adafruit MCP9808 Library Documentation', - author, 'AdafruitMCP9808Library', 'One line description of project.', - 'Miscellaneous'), -] - -# Documents to append as an appendix to all manuals. -# -# texinfo_appendices = [] - -# If false, no module index is generated. -# -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# -# texinfo_show_urls = 'footnote' - -# If true, do not generate a @detailmenu in the "Top" node's menu. -# -# texinfo_no_detailmenu = False - -intersphinx_mapping = {'python': ('https://docs.python.org/3', None), - 'CircuitPython': ('https://docs.circuitpython.org/en/latest/', None)} +# author, documentclass [howto, manual, or own class diff --git a/conf.py.bak.20260318032101 b/conf.py.bak.20260318032101 new file mode 100644 index 0000000..e0747f6 --- /dev/null +++ b/conf.py.bak.20260318032101 @@ -0,0 +1,360 @@ +# -*- coding: utf-8 -*- + +# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries +# +# SPDX-License-Identifier: MIT + +# Adafruit MCP9808 Library documentation build configuration file, created by +# sphinx-quickstart on Fri Nov 11 07:42:21 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +import os +import sys +sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +# +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'README' + +# General information about the project. +project = u'Adafruit MCP9808 Library' +copyright = u'2017 Scott Shawcroft' +author = u'Scott Shawcroft' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = u'1.0' +# The full version, including alpha/beta/rc tags. +release = u'1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# +# today = '' +# +# Else, today_fmt is used as the format for a strftime call. +# +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# +default_role = "any" + +# If true, '()' will be appended to :func: etc. cross-reference text. +# +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +if not on_rtd: # only import and set the theme if we're building docs locally + try: + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), '.'] + except: + html_theme = 'default' + html_theme_path = ['.'] +else: + html_theme_path = ['.'] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +# html_theme_path = [] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +# +# html_title = u'Adafruit MCP9808 Library v1.0' + +# A shorter title for the navigation bar. Default is the same as html_title. +# +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# +# html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# +# html_additional_pages = {} + +# If false, no module index is generated. +# +# html_domain_indices = True + +# If false, no index is generated. +# +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'AdafruitMCP9808Librarydoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'AdafruitMCP9808Library.tex', u'Adafruit MCP9808 Library Documentation', + u'Phiilip Moyer', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# +# latex_use_parts = False + +# If true, show page references after internal links. +# +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# +# latex_appendices = [] + +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True + +# If false, no module index is generated. +# +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'adafruitMCP9808library', u'Adafruit MCP9808 Library Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +# +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'AdafruitMCP9808Library', u'Adafruit MCP9808 Library Documentation', + author, 'AdafruitMCP9808Library', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# +# texinfo_appendices = [] + +# If false, no module index is generated. +# +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# +# texinfo_no_detailmenu = False + +intersphinx_mapping = {'python': ('https://docs.python.org/3', None), + 'CircuitPython': ('https://docs.circuitpython.org/en/latest/', None)} diff --git a/tests/test_make_cookies.py b/tests/test_make_cookies.py index f814e81..3454ba9 100644 --- a/tests/test_make_cookies.py +++ b/tests/test_make_cookies.py @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries +# SPDX-FileCopyrightText: 2024 Scott Shawcroft, written for Adafruit Industries # # SPDX-License-Identifier: MIT @@ -10,42 +10,43 @@ from cookiecutter.main import cookiecutter - working_dir = pathlib.Path() -output_dir = working_dir / '.cookie_test' +output_dir = working_dir / ".cookie_test" -cookie_json_path = working_dir / 'cookiecutter.json' +cookie_json_path = working_dir / "cookiecutter.json" if not cookie_json_path.exists(): - raise RuntimeError('Please run pytest from the top-most directory.') + raise RuntimeError("Please run pytest from the top-most directory.") cookie_json = None -with open(cookie_json_path.resolve(), 'r') as cookie_file: +with open(cookie_json_path.resolve(), "r") as cookie_file: cookie_json = json.load(cookie_file) + def is_pre_commit_clean(cookie_dir): """Check that the directory is pre-commit clean side effect: creates a git repository in the cookie_dir""" subprocess.check_call(["git", "init"], cwd=cookie_dir) subprocess.check_call(["git", "add", "."], cwd=cookie_dir) - subprocess.check_call(["pre-commit", "run", "--all-files", "--show-diff-on-failure"], cwd=cookie_dir) + subprocess.check_call( + ["pre-commit", "run", "--all-files", "--show-diff-on-failure"], cwd=cookie_dir + ) return True -def compare_template_dirs(*, library_name='test', library_prefix=None): - """ Helper function to compare the results of generated files, - to the available files in the template. - :param: str library_name: Name used for the template's `library_name` - prompt. Default: 'test' - :param: None,str library_prefix: The value used for the template's - `library_prefix` prompt. Default: None +def compare_template_dirs(*, library_name="test", library_prefix=None): + """Helper function to compare the results of generated files, + to the available files in the template. + + :param library_name: Name used for the template's `library_name` prompt. + :param library_prefix: The value used for the template's `library_prefix` prompt. """ cookie_template_path = working_dir / "{{ cookiecutter.__dirname }}" if library_prefix: - generated_folder_name = "{}_CircuitPython_{}".format(library_prefix, library_name) + generated_folder_name = f"{library_prefix}_CircuitPython_{library_name}" else: - generated_folder_name = "CircuitPython_{}".format(library_name) + generated_folder_name = f"CircuitPython_{library_name}" generated_path = output_dir / generated_folder_name assert generated_path.exists() @@ -54,57 +55,54 @@ def compare_template_dirs(*, library_name='test', library_prefix=None): template_files = set() for file in cookie_template_path.iterdir(): - if '{' in file.name: + if "{" in file.name: if not library_prefix: - base_name = file.with_name('CircuitPython_{}'.format(library_name)) - template_files.add( - base_name.with_suffix(file.suffix).name - ) + base_name = file.with_name(f"CircuitPython_{library_name}") + template_files.add(base_name.with_suffix(file.suffix).name) else: - base_name = file.with_name('{}_CircuitPython_{}'.format( - library_prefix, - library_name - )) - template_files.add( - base_name.with_suffix(file.suffix).name + base_name = file.with_name( + f"{library_prefix}_CircuitPython_{library_name}" ) + template_files.add(base_name.with_suffix(file.suffix).name) else: template_files.add(file.name) return 0 <= len(template_files.difference(set(generated_files))) + def test_new_cookiecutter_only_required_entries(): - """ Basic test of running cookiecutter, supplying info only to the - required fields (cookiecutter.json values of 'null'). + """Basic test of running cookiecutter, supplying info only to the + required fields (cookiecutter.json values of 'null'). """ test_context = {} for key, value in cookie_json.items(): - if not key.startswith('_'): - if value == None: - test_context[key] = 'test' + if not key.startswith("_"): + if value is None: + test_context[key] = "test" new_cookie = cookiecutter( str(working_dir.resolve()), no_input=True, output_dir=str(output_dir.resolve()), overwrite_if_exists=True, - extra_context=test_context + extra_context=test_context, ) - assert new_cookie.rpartition(os.sep)[2] == 'Adafruit_CircuitPython_test' + assert new_cookie.rpartition(os.sep)[2] == "Adafruit_CircuitPython_test" assert compare_template_dirs(library_prefix="Adafruit") assert is_pre_commit_clean(new_cookie) + def test_new_cookiecutter_all_entries(): - """ Basic test of running cookiecutter, supplying info for all fields. - All fields will have 'test' except where specific values are required, so this is only a - minimal & cursory test. + """Basic test of running cookiecutter, supplying info for all fields. + All fields will have 'test' except where specific values are required, so this is only a + minimal & cursory test. """ test_context = {} for key in cookie_json: - if not key.startswith('_'): + if not key.startswith("_"): test_context[key] = "Community" if key == "target_bundle" else "test" new_cookie = cookiecutter( @@ -112,9 +110,9 @@ def test_new_cookiecutter_all_entries(): no_input=True, output_dir=str(output_dir.resolve()), overwrite_if_exists=True, - extra_context=test_context + extra_context=test_context, ) - assert new_cookie.rpartition(os.sep)[2] == 'Test_CircuitPython_test' - assert compare_template_dirs(library_prefix='Test') + assert new_cookie.rpartition(os.sep)[2] == "Test_CircuitPython_test" + assert compare_template_dirs(library_prefix="Test") assert is_pre_commit_clean(new_cookie) diff --git a/tests/test_make_cookies.py.bak.20260318032113 b/tests/test_make_cookies.py.bak.20260318032113 new file mode 100644 index 0000000..f814e81 --- /dev/null +++ b/tests/test_make_cookies.py.bak.20260318032113 @@ -0,0 +1,120 @@ +# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries +# +# SPDX-License-Identifier: MIT + +import json +import os +import pathlib +import subprocess +import sys + +from cookiecutter.main import cookiecutter + + +working_dir = pathlib.Path() +output_dir = working_dir / '.cookie_test' + +cookie_json_path = working_dir / 'cookiecutter.json' +if not cookie_json_path.exists(): + raise RuntimeError('Please run pytest from the top-most directory.') + +cookie_json = None +with open(cookie_json_path.resolve(), 'r') as cookie_file: + cookie_json = json.load(cookie_file) + +def is_pre_commit_clean(cookie_dir): + """Check that the directory is pre-commit clean + + side effect: creates a git repository in the cookie_dir""" + subprocess.check_call(["git", "init"], cwd=cookie_dir) + subprocess.check_call(["git", "add", "."], cwd=cookie_dir) + subprocess.check_call(["pre-commit", "run", "--all-files", "--show-diff-on-failure"], cwd=cookie_dir) + return True + +def compare_template_dirs(*, library_name='test', library_prefix=None): + """ Helper function to compare the results of generated files, + to the available files in the template. + + :param: str library_name: Name used for the template's `library_name` + prompt. Default: 'test' + :param: None,str library_prefix: The value used for the template's + `library_prefix` prompt. Default: None + """ + + cookie_template_path = working_dir / "{{ cookiecutter.__dirname }}" + if library_prefix: + generated_folder_name = "{}_CircuitPython_{}".format(library_prefix, library_name) + else: + generated_folder_name = "CircuitPython_{}".format(library_name) + + generated_path = output_dir / generated_folder_name + assert generated_path.exists() + + generated_files = [file.name for file in generated_path.iterdir()] + + template_files = set() + for file in cookie_template_path.iterdir(): + if '{' in file.name: + if not library_prefix: + base_name = file.with_name('CircuitPython_{}'.format(library_name)) + template_files.add( + base_name.with_suffix(file.suffix).name + ) + else: + base_name = file.with_name('{}_CircuitPython_{}'.format( + library_prefix, + library_name + )) + template_files.add( + base_name.with_suffix(file.suffix).name + ) + else: + template_files.add(file.name) + + return 0 <= len(template_files.difference(set(generated_files))) + +def test_new_cookiecutter_only_required_entries(): + """ Basic test of running cookiecutter, supplying info only to the + required fields (cookiecutter.json values of 'null'). + """ + + test_context = {} + for key, value in cookie_json.items(): + if not key.startswith('_'): + if value == None: + test_context[key] = 'test' + + new_cookie = cookiecutter( + str(working_dir.resolve()), + no_input=True, + output_dir=str(output_dir.resolve()), + overwrite_if_exists=True, + extra_context=test_context + ) + + assert new_cookie.rpartition(os.sep)[2] == 'Adafruit_CircuitPython_test' + assert compare_template_dirs(library_prefix="Adafruit") + assert is_pre_commit_clean(new_cookie) + +def test_new_cookiecutter_all_entries(): + """ Basic test of running cookiecutter, supplying info for all fields. + All fields will have 'test' except where specific values are required, so this is only a + minimal & cursory test. + """ + + test_context = {} + for key in cookie_json: + if not key.startswith('_'): + test_context[key] = "Community" if key == "target_bundle" else "test" + + new_cookie = cookiecutter( + str(working_dir.resolve()), + no_input=True, + output_dir=str(output_dir.resolve()), + overwrite_if_exists=True, + extra_context=test_context + ) + + assert new_cookie.rpartition(os.sep)[2] == 'Test_CircuitPython_test' + assert compare_template_dirs(library_prefix='Test') + assert is_pre_commit_clean(new_cookie) diff --git a/{{ cookiecutter.__dirname }}/examples/{{ cookiecutter.__libname }}_simpletest.py b/{{ cookiecutter.__dirname }}/examples/{{ cookiecutter.__libname }}_simpletest.py index 5361dca..2d100da 100644 --- a/{{ cookiecutter.__dirname }}/examples/{{ cookiecutter.__libname }}_simpletest.py +++ b/{{ cookiecutter.__dirname }}/examples/{{ cookiecutter.__libname }}_simpletest.py @@ -2,3 +2,5 @@ # SPDX-FileCopyrightText: Copyright (c) {% now 'utc', '%Y' %} {{ cookiecutter.author_name }}{% if cookiecutter.company %} for {{ cookiecutter.company }}{% endif %} # # SPDX-License-Identifier: Unlicense +# +# Update actions according to https://github.com/adafruit/circuitpython/issues/10888 \ No newline at end of file diff --git a/{{ cookiecutter.__dirname }}/examples/{{ cookiecutter.__libname }}_simpletest.py.bak.20260318032119 b/{{ cookiecutter.__dirname }}/examples/{{ cookiecutter.__libname }}_simpletest.py.bak.20260318032119 new file mode 100644 index 0000000..5361dca --- /dev/null +++ b/{{ cookiecutter.__dirname }}/examples/{{ cookiecutter.__libname }}_simpletest.py.bak.20260318032119 @@ -0,0 +1,4 @@ +# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries +# SPDX-FileCopyrightText: Copyright (c) {% now 'utc', '%Y' %} {{ cookiecutter.author_name }}{% if cookiecutter.company %} for {{ cookiecutter.company }}{% endif %} +# +# SPDX-License-Identifier: Unlicense