knit-graphs 0.0.5__py3-none-any.whl → 0.0.7__py3-none-any.whl

knit_graphs-0.0.5.dist-info/licenses/LICENSE → LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2024 Megan Hofmann
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2024 Megan Hofmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,75 @@
+# knit_graphs
+
+[![PyPI - Version](https://img.shields.io/pypi/v/knit-graphs.svg)](https://pypi.org/project/knit-graphs)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/knit-graphs.svg)](https://pypi.org/project/knit-graphs)
+
+-----
+## Description
+The knit-graphs packaged provides a data structure for representing knitted structures formed of loops of yarn (nodes) connected by various edge structures. Loops are connected by: floats (yarn-edges) in a yarn graph structure, stitch edges (loops pulled through loops), and crossed over each other in a wale-braid structure.
+
+Knit graphs provide a powerful tool for representing knitted structures for digital fabrication systems such as knitting machine programming languages and design tools.
+
+Additional details about this knit-graph construction are available in the ACM publication:
+["KnitPicking Texture: Programming and Modifying Complex Knitted Textures for Machine and Hand Knitting"](https://doi.org/10.1145/3332165.3347886)
+
+## Table of Contents
+- [Description](#description)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Knit Graph Generators](#knit-graph-generators)
+  - [Visualizing Knit Graphs](#visualizing-knit-graphs)
+- [Credits](#credits)
+- [License](#license)
+
+
+
+## Installation
+
+```console
+pip install knit-graphs
+```
+
+## Usage
+
+### Knit Graph Generators
+The [knit-graph-generators subpackage](https://github.com/mhofmann-Khoury/knit_graph/tree/main/src/knit_graphs/knit_graph_generators) provides a library of basic knit graphs to generate such as casting on loops of a knitted structure, creating Jersey (aka Stockinette) tubes and swatches, and other basic textures.
+For example, to generate a swatch of knit-purl ribbing use the following:
+
+```python
+from knit_graphs.basic_knit_graph_generators import kp_rib_swatch
+
+width = 10
+height = 10
+kp_rib_swatch = kp_rib_swatch(width, height)
+```
+Additional examples of knitgraph generator usage can be found in the [Knit_Graph test module](https://github.com/mhofmann-Khoury/knit_graph/blob/main/tests/test_Knit_Graph.py).
+
+Knitgraphs can be created without generators. We encourage users to review the generators as simple examples on creating a knit graph programmatically.
+
+### Visualizing Knit Graphs
+We provide simple support for visualizing knit graphs. This is primarily used to debugging simple knit graph programs.
+
+For example, we can visualize a swatch of seed stitch (checkered knit and purl stitches) with the following code.
+
+```python
+from knit_graphs.basic_knit_graph_generators import seed_swatch
+from knit_graphs.knit_graph_visualizer.Stitch_Visualizer import visualize_stitches
+
+width = 4
+height = 4
+swatch = seed_swatch(width, height)
+visualize_stitches(swatch)
+```
+The visualizer shows knit stitches (loops pulled from the back of the fabric to the front) as blue edges and purl stitches (loops pulled from the front to back) (aka back-knits) as red edges. Loop nodes are circles labeled with their time-ordered index and colored to match their yarn (defaults to dark green). The yarn edges (aka floats) connecting them are made of thin edges the same color as the loop nodes.
+
+Additional examples of using the visualizer are available in the [Stitch Visualizer Tests Module](https://github.com/mhofmann-Khoury/knit_graph/blob/main/tests/test_Stitch_Visualizer.py)
+
+## Credits
+The design of this data scructure was completed by the authors of
+["KnitPicking Texture: Programming and Modifying Complex Knitted Textures for Machine and Hand Knitting"](https://doi.org/10.1145/3332165.3347886).
+
+The inclusion of the Artin-Braide wale crossing construction was inspired by ["An Artin Braid Group Representation of Knitting Machine State with Applications to Validation and Optimization of Fabrication Plans"](https://doi.org/10.1109/ICRA48506.2021.9562113) by Jenny Lin and James McCann.
+
+## License
+
+`knit-graphs` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/api/knit_graphs.artin_wale_braids.rst

@@ -0,0 +1,58 @@
+knit\_graphs.artin\_wale\_braids package
+========================================
+
+.. automodule:: knit_graphs.artin_wale_braids
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+----------
+
+knit\_graphs.artin\_wale\_braids.Crossing\_Direction module
+-----------------------------------------------------------
+
+.. automodule:: knit_graphs.artin_wale_braids.Crossing_Direction
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.artin\_wale\_braids.Loop\_Braid\_Graph module
+----------------------------------------------------------
+
+.. automodule:: knit_graphs.artin_wale_braids.Loop_Braid_Graph
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.artin\_wale\_braids.Wale module
+--------------------------------------------
+
+.. automodule:: knit_graphs.artin_wale_braids.Wale
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.artin\_wale\_braids.Wale\_Braid module
+---------------------------------------------------
+
+.. automodule:: knit_graphs.artin_wale_braids.Wale_Braid
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.artin\_wale\_braids.Wale\_Braid\_Word module
+---------------------------------------------------------
+
+.. automodule:: knit_graphs.artin_wale_braids.Wale_Braid_Word
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.artin\_wale\_braids.Wale\_Group module
+---------------------------------------------------
+
+.. automodule:: knit_graphs.artin_wale_braids.Wale_Group
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/knit_graphs.rst

@@ -0,0 +1,74 @@
+knit\_graphs package
+====================
+
+.. automodule:: knit_graphs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   knit_graphs.artin_wale_braids
+
+Submodules
+----------
+
+knit\_graphs.Course module
+--------------------------
+
+.. automodule:: knit_graphs.Course
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.Knit\_Graph module
+-------------------------------
+
+.. automodule:: knit_graphs.Knit_Graph
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.Knit\_Graph\_Visualizer module
+-------------------------------------------
+
+.. automodule:: knit_graphs.Knit_Graph_Visualizer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.Loop module
+------------------------
+
+.. automodule:: knit_graphs.Loop
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.Pull\_Direction module
+-----------------------------------
+
+.. automodule:: knit_graphs.Pull_Direction
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.Yarn module
+------------------------
+
+.. automodule:: knit_graphs.Yarn
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+knit\_graphs.basic\_knit\_graph\_generators module
+--------------------------------------------------
+
+.. automodule:: knit_graphs.basic_knit_graph_generators
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/conf.py

@@ -0,0 +1,335 @@
+"""
+    Configuration file for the Sphinx documentation builder.
+    =============================================================================
+    SPHINX DOCUMENTATION CONFIGURATION
+    =============================================================================
+    This file configures how Sphinx generates documentation from your Python code.
+    For the full list of built-in configuration values, see:
+    https://www.sphinx-doc.org/en/master/usage/configuration.html
+"""
+
+import os
+import sys
+from datetime import datetime
+from importlib.metadata import PackageNotFoundError, version
+
+# =============================================================================
+# PATH SETUP
+# =============================================================================
+# Add the project root and source directory to Python path so Sphinx can import your modules
+
+# Path to your source code (adjust if not using src/ layout)
+sys.path.insert(0, os.path.abspath('..'))  # Project root
+sys.path.insert(0, os.path.abspath('../src'))  # Source directory
+sys.path.insert(0, os.path.abspath('.'))  # Docs directory
+
+# =============================================================================
+# PROJECT INFORMATION
+# =============================================================================
+
+project = 'knit-graphs'
+copyright = f'{datetime.now().year}, Megan Hofmann'
+author = 'Megan Hofmann'
+
+try:
+    # Get version from installed package metadata
+    # This reads from pyproject.toml when the package is installed
+    version = version("knit-graphs")
+except PackageNotFoundError:
+    # Package is not installed (e.g., during development)
+    # This happens when running from source without installation
+    version = "0.0.0+dev"
+
+release = version
+
+# =============================================================================
+# GENERAL CONFIGURATION
+# =============================================================================
+
+# Extensions to enable (these add functionality to Sphinx)
+extensions = [
+    # Core Sphinx extensions
+    'sphinx.ext.autodoc',  # Generate docs from docstrings
+    'sphinx.ext.autosummary',  # Generate summary tables automatically
+    'sphinx.ext.viewcode',  # Add [source] links to documentation
+    'sphinx.ext.napoleon',  # Support Google/NumPy docstring styles
+    'sphinx.ext.intersphinx',  # Link to other project docs (e.g., Python docs)
+    'sphinx.ext.githubpages',  # Publish to GitHub Pages (.nojekyll file)
+    'sphinx.ext.todo',  # Support TODO items in docs
+    'sphinx.ext.coverage',  # Check documentation coverage
+    'sphinx.ext.doctest',  # Test code snippets in documentation
+
+    # Third-party extensions (these need to be installed)
+    'sphinx_autodoc_typehints',  # Better type hint rendering
+    'myst_parser',  # Support for Markdown files (optional)
+]
+
+# =============================================================================
+# SOURCE FILE CONFIGURATION
+# =============================================================================
+
+# File extensions that Sphinx will process
+source_suffix = {
+    '.rst': None,  # RestructuredText (default)
+    '.md': 'myst_parser',  # Markdown (requires myst_parser extension)
+}
+
+# The master toctree document (main page)
+master_doc = 'index'
+
+# Files and directories to exclude from processing
+exclude_patterns = [
+    '_build',  # Build output directory
+    'Thumbs.db',  # Windows thumbnail cache
+    '.DS_Store',  # macOS metadata
+    '**.ipynb_checkpoints',  # Jupyter notebook checkpoints
+]
+
+# =============================================================================
+# HTML OUTPUT CONFIGURATION
+# =============================================================================
+
+# The theme to use for HTML pages
+html_theme = 'sphinx_rtd_theme'  # Read the Docs theme (clean, professional)
+
+# Directories containing static files (CSS, JS, images)
+html_static_path = ['_static']
+
+
+# Theme-specific options
+html_theme_options = {
+    'logo_only': False,  # Show project name with logo
+    'display_version': True,  # Show version in sidebar
+    'prev_next_buttons_location': 'bottom',  # Navigation button placement
+    'style_external_links': True,  # Style external links differently
+    'vcs_pageview_mode': '',  # Version control integration
+    'style_nav_header_background': '#2980B9',  # Header background color
+
+    # Table of contents options
+    'collapse_navigation': True,  # Collapse subsections in nav
+    'sticky_navigation': True,  # Keep navigation visible on scroll
+    'navigation_depth': 4,  # Maximum navigation depth
+    'includehidden': True,  # Include hidden toctrees
+    'titles_only': False,  # Show subsection titles in nav
+}
+
+# Additional HTML options
+html_title = f'{project} Documentation'  # Browser window title
+html_short_title = project  # Short title for navigation
+
+
+# html_logo = '_static/logo.png'
+# html_favicon = '_static/favicon.ico'
+
+# Show "Edit on GitHub" links (requires proper URL)
+# html_context = {
+#     'github_user': 'your-username',
+#     'github_repo': 'your-repo-name',
+#     'github_version': 'main',
+#     'doc_path': 'docs',
+# }
+
+# =============================================================================
+# AUTODOC CONFIGURATION
+# =============================================================================
+# Controls how automatic documentation is generated from Python code
+
+# Default options for all autodoc directives
+autodoc_default_options = {
+    'members': True,  # Include all members
+    'member-order': 'bysource',  # Order members as they appear in source
+    'special-members': '__init__',  # Include __init__ methods
+    'undoc-members': True,  # Include members without docstrings
+    'exclude-members': '__weakref__',  # Exclude certain members
+    'show-inheritance': True,  # Show class inheritance
+    'inherited-members': True,  # Include inherited methods
+}
+
+# How to display class signatures
+autodoc_class_signature = "mixed"  # Show __init__ parameters with class
+
+# Order of members in documentation
+autodoc_member_order = 'bysource'  # bysource, alphabetical, or groupwise
+
+# Mock imports for modules that might not be available during doc building
+# Add any modules that cause import errors during doc building
+autodoc_mock_imports = [
+    # 'numpy',
+    # 'pandas',
+    # 'some_optional_dependency',
+]
+
+# =============================================================================
+# AUTOSUMMARY CONFIGURATION
+# =============================================================================
+# Controls automatic generation of summary tables
+
+autosummary_generate = True  # Generate stub pages for autosummary
+autosummary_imported_members = True  # Include imported members
+
+# =============================================================================
+# NAPOLEON CONFIGURATION (DOCSTRING STYLES)
+# =============================================================================
+# Configures support for Google and NumPy style docstrings
+
+napoleon_google_docstring = True  # Parse Google-style docstrings
+napoleon_numpy_docstring = True  # Parse NumPy-style docstrings
+napoleon_include_init_with_doc = True  # Include __init__ docstring with class
+napoleon_include_private_with_doc = False  # Don't document private members
+napoleon_include_special_with_doc = True  # Document special methods (__str__, etc.)
+napoleon_use_admonition_for_examples = False  # Style for Examples sections
+napoleon_use_admonition_for_notes = False  # Style for Notes sections
+napoleon_use_admonition_for_references = False  # Style for References sections
+napoleon_use_ivar = False  # Use :ivar: for instance variables
+napoleon_use_param = True  # Use :param: for parameters
+napoleon_use_rtype = True  # Use :rtype: for return types
+napoleon_preprocess_types = False  # Preprocess type annotations
+napoleon_type_aliases = None  # Custom type aliases
+napoleon_attr_annotations = True  # Include attribute annotations
+
+# =============================================================================
+# INTERSPHINX CONFIGURATION
+# =============================================================================
+# Links to external documentation
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'pandas': ('https://pandas.pydata.org/pandas-docs/stable/', None),
+    'matplotlib': ('https://matplotlib.org/stable/', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/', None),
+    'sklearn': ('https://scikit-learn.org/stable/', None),
+    'typing': ('https://typing.readthedocs.io/en/latest/', None),
+}
+
+# =============================================================================
+# TYPE HINTS CONFIGURATION
+# =============================================================================
+# Controls how type hints are displayed in documentation
+
+typehints_fully_qualified = False  # Use short names for types
+always_document_param_types = True  # Always show parameter types
+typehints_document_rtype = True  # Document return types
+typehints_use_rtype = True  # Use :rtype: directive for return types
+
+# =============================================================================
+# TODO EXTENSION CONFIGURATION
+# =============================================================================
+
+todo_include_todos = True  # Include TODO items in documentation
+todo_emit_warnings = True  # Warn about TODO items during build
+
+# =============================================================================
+# COVERAGE EXTENSION CONFIGURATION
+# =============================================================================
+# Checks what's documented vs what's not
+
+coverage_ignore_modules = [
+    #  Add modules to ignore in coverage reports
+]
+coverage_ignore_functions = [
+    #  Add functions to ignore in coverage reports
+]
+coverage_ignore_classes = [
+    #  Add classes to ignore in coverage reports
+]
+
+# =============================================================================
+# ADDITIONAL CUSTOMIZATION
+# =============================================================================
+
+# Control how module names are displayed
+add_module_names = False  # Don't prepend module names to functions
+
+# Show author information in output
+show_authors = False  # Don't show author info by default
+
+# Syntax highlighting style
+pygments_style = 'sphinx'  # Code highlighting theme
+
+# Language for content that doesn't specify a language
+language = 'en'
+
+
+# =============================================================================
+# CUSTOM FUNCTIONS AND SETUP
+# =============================================================================
+
+def autodoc_skip_member(app, what, name, obj, skip, options):
+    """
+    Custom function to control which members are included in documentation.
+
+    Args:
+        app: The Sphinx application instance
+        what: The type of the object (module, class, function, etc.)
+        name: The fully qualified name of the object
+        obj: The object itself
+        skip: Boolean indicating if this member should be skipped
+        options: The options given to the directive
+
+    Returns:
+        Boolean indicating whether to skip this member
+    """
+    # Add custom logic to skip certain members
+    # Example: Skip private methods that start with underscore
+    # if name.startswith('_') and not name.startswith('__'):
+    #     return True
+
+    return skip
+
+
+def setup(app):
+    """
+    Custom Sphinx setup function.
+    This function is called when Sphinx initializes and allows you to
+    add custom functionality, connect to events, etc.
+
+    Args:
+        app: The Sphinx application instance
+    """
+    # Connect custom functions to Sphinx events
+    app.connect('autodoc-skip-member', autodoc_skip_member)
+
+    # Return extension metadata
+    return {
+        'version': version,
+        'parallel_read_safe': True,
+        'parallel_write_safe': True,
+    }
+
+# =============================================================================
+# CHECKLIST FOR SPHINX SETUP
+# =============================================================================
+# When using this configuration:
+#
+# 1. BASIC SETUP:
+#    - [ ] Update project, author, and copyright information
+#    - [ ] Set correct version/release values
+#    - [ ] Verify source code paths are correct
+#    - [ ] Create docs/_static/ directory for custom files
+#
+# 2. CONTENT CREATION:
+#    - [ ] Create docs/index.rst (main page)
+#    - [ ] Create docs/installation.rst (installation guide)
+#    - [ ] Create docs/usage.rst (usage examples)
+#    - [ ] Create docs/api.rst (API reference)
+#
+# 3. CUSTOMIZATION:
+#    - [ ] Choose and configure theme options
+#    - [ ] Add logo and favicon to _static/
+#    - [ ] Create custom CSS/JS if needed
+#    - [ ] Configure intersphinx for your dependencies
+#
+# 4. TESTING:
+#    - [ ] Run: poetry run sphinx-build docs/ docs/_build/html/
+#    - [ ] Check output in docs/_build/html/index.html
+#    - [ ] Fix any warnings or errors
+#
+# 5. GITHUB PAGES:
+#    - [ ] Ensure githubpages extension is enabled
+#    - [ ] Configure GitHub repository Pages settings
+#    - [ ] Test deployment with GitHub Actions workflow
+#
+# COMMON COMMANDS:
+#   poetry run sphinx-apidoc -o docs/source/api src/your_project_name/ --force --module-first       # Generate API docs
+#   poetry run sphinx-build docs/source/ docs/build/html/ # Build documentation