Skip to content

Fix #258: Update actions #259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
IlyasFardaouix wants to merge 1 commit into from
Closed

Fix #258: Update actions #259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <https://cookiecutter.readthedocs.io/en/latest/installation.html#windows>`_
The Python environment can be tricky sometimes in Windows. Use this documentation page for steps and tips on Windows installation: `Cookiecutter Installation - Windows <https://cookiecutter.readthedocs.io/en/latest/installation.html#windows>`_


<library>.py & /examples/<library>_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 <library>.py and /examples/<library>_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 <library>.py and /examples/<library>_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!
100 changes: 100 additions & 0 deletions README.rst.bak.20260318032052
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/overview>`_ The section for using cookiecutter is `here <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/creating-a-library#cookie-cutter>`_.

.. 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 <https://github.com/adafruit/Adafruit_CircuitPython_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 <https://github.com/adafruit/Adafruit_CircuitPython_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 <https://cookiecutter.readthedocs.io/en/latest/installation.html#windows>`_


<library>.py & /examples/<library>_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 <library>.py and /examples/<library>_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!
160 changes: 37 additions & 123 deletions conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,8 @@
#
import os
import sys
sys.path.insert(0, os.path.abspath('.'))

sys.path.insert(0, os.path.abspath("."))

# -- General configuration ------------------------------------------------

Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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 = []
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Loading
Loading