Merge pull request #1 from MichaelHaussmann/dev

Dev to main

README.md

@@ -1,19 +1,23 @@
-
 # resolva
 
-Simple and fast path template resolver.  
-Inspired by and derived from Lucidity.
+## What is resolva ?
+
+**resolva** is a simple and fast **path template resolver**:<br>
+A python library that extracts data from a string by matching configured patterns.  
 
+It is inspired by and derived from [Lucidity](https://gitlab.com/4degrees/lucidity), which in turn is loosely inspired by [Shotgrid Toolkit (SGTK) templating](https://github.com/shotgunsoftware/tk-config-default/blob/master/core/templates.yml). 
 
-## What is resolva ?
 
-**resolva** is a python library that extracts data from a string by matching configurated patterns.
+Full documentation: [resolva.readthedocs.io](https://resolva.readthedocs.io).
 
-`"/mnt/prods/hamlet/shots/sq010"` >>  
-`"/mnt/prods/{prod}/shots/{seq}"` >>  
-`{"prod": "hamlet", "seq": "sq010"}`
 
-#### Process
+### How does it work ?
+
+- For a configured pattern, eg: `/mnt/prods/{prod}/shots/{seq}` 
+- Given a path, eg: `/mnt/prods/hamlet/shots/sq010`  
+- Resolva will extract and return this: `{"prod": "hamlet", "seq": "sq010"}`
+
+### Process
 
 1. for a path or string input,
 2. the resolver loops through a series of configured patterns, 
@@ -30,7 +34,7 @@ Template based path resolving is a typical need in CG pipeline tools.
 
 Examples include:
 
-- [Shotgrid Toolkit (SGTK)](https://github.com/shotgunsoftware/tk-config-default/blob/master/core/templates.yml) - Leading commercial CG and VFX Project Management and pipeline toolkit
+- [Shotgrid Toolkit (SGTK)](https://github.com/shotgunsoftware/tk-config-default2/blob/master/core/templates.yml) - Leading commercial CG and VFX Project Management and pipeline toolkit
 - [CGWire's kitsu file trees](https://zou.cg-wire.com/file_trees) - Kitsu is an Open Source collaboration platform for Animation and VFX studios. 
 - [Lucidity](https://gitlab.com/4degrees/lucidity) - Inspired by SGTK templating, in turn inspiration and base of **resolva**
 - [spil](https://github.com/MichaelHaussmann/spil) - Uses **resolva** at its core
@@ -63,18 +67,15 @@ Detected type "maya_file" and extracted
 {"prod": "hamlet", "seq": "sq010", "shot": "sh010", "version": "v012", "ext": "ma"}
 ```
 
-
-
 ## Features
 
-- simple template format     
+- Simple template format     
   - Example: `/{shot}/{version}/{name}.{extension:(ma|mb)}`
   - handles duplicate placeholders
-- very simple API
+- Very simple API
   - resolve with one, first, or all patterns
   - format with one, first, or all patterns
-  - format including reverse resolve check
-- high speed using caches
+- High speed thanks to caches
   - instance cache (keep regex compilations in memory)
   - lru_caches (speed up immutable resolves)
 
@@ -114,34 +115,40 @@ If you need one of these, go for the original :)
 
 ## Installation
 
-**resolva** works in Python >=3.7.  
+**resolva** works in Python >=3.7.<br>
 It is available on pypi and can be installed using `pip install resolva`,  
-or from github `pip install git+https://github.com/MichaelHaussmann/resolva.git`
 
 **resolva** is open source, License: MIT.
 
-### TODO:
 
-- docstrings (+doctests) 
-- pytests calling the existing tests
-- Usage documentation, dev documentation + API documentation (readthedocs or github?)
-- black, refurb, etc.
-- pip installable and python bound rust implementation 
-
-
-### Acknowledgements
+## Acknowledgements
 
 **resolva** is inspired by, and derived from **Lucidity**.
 
-#### Lucidity 
+### Lucidity 
 
-https://gitlab.com/4degrees/lucidity/  
-https://lucidity.readthedocs.io  
-copyright: Copyright (c) 2013 Martin Pengelly-Phillips  
+[https://gitlab.com/4degrees/lucidity](https://gitlab.com/4degrees/lucidity)<br>
+[https://lucidity.readthedocs.io](https://lucidity.readthedocs.io)<br>
+copyright: Copyright (c) 2013 Martin Pengelly-Phillips<br>  
 licence: Apache License, Version 2.0
 
-#### resolva
+### resolva
 
-https://github.com/MichaelHaussmann/resolva  
-(c) 2024 Michael Haussmann  
+[https://github.com/MichaelHaussmann/resolva](https://github.com/MichaelHaussmann/resolva)<br>
+[https://resolva.readthedocs.io](https://resolva.readthedocs.io)<br>
+(c) 2024 Michael Haussmann<br>
 licence: MIT
+
+
+## Interested ?
+
+We'd love to hear from you.<br>
+We are interested in any kind of feedback: comments, questions, issues, pull requests.
+
+Do not hesitate to [start a discussion on github](https://github.com/MichaelHaussmann/resolva/discussions/new/choose).
+
+<br>
+
+![python](https://img.shields.io/badge/PYTHON-blue?style=for-the-badge&logo=Python&logoColor=white)
+![type checker](https://img.shields.io/badge/Type%20checker-MYPY-dodgerblue?style=for-the-badge&labelColor=abcdef)
+![gitHub release](https://img.shields.io/github/v/release/MichaelHaussmann/resolva?style=for-the-badge&color=orange&labelColor=sandybrown)

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     = .
+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/api.rst

@@ -0,0 +1,9 @@
+API
+=====
+
+Resolver
+---
+
+.. autoclass:: resolva.Resolver
+   :members:
+

docs/conf.py

@@ -0,0 +1,106 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# Getting started with sphinx
+# https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html
+
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+###################################################################################################
+# Sys path setting for autodoc (needs to be able to import the code)
+import sys
+from pathlib import Path
+here = Path(__file__)
+root = here.parent.parent
+venv = root / 'venv' / 'lib' / 'python3.7' / 'site-packages'
+print(root)
+sys.path.append(str(root))
+sys.path.append(str(venv))
+# sys.exit()
+
+###################################################################################################
+# General options
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+project = 'Resolva'
+copyright = '2024, Michael Haussmann'
+author = 'Michael Haussmann'
+release = '0.1.0'
+
+extensions = ['myst_parser',
+    # 'sphinx.ext.duration',
+    'sphinx.ext.napoleon',  # Google format doctrings -> reSt before parsed
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+	# 'sphinx.ext.todo',
+	'sphinx.ext.viewcode',
+]
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+###################################################################################################
+# HTML options
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_title = "Resolva Documentation"
+# html_logo = "img/small.png"
+html_favicon = "img/favicon.ico"
+
+html_theme_options = {
+	# 'logo_only': True,
+	'display_version': True,
+	'prev_next_buttons_location': 'bottom',
+	'style_external_links': True,    # Toc options
+	'collapse_navigation': False,
+	# 'sticky_navigation': False,
+	'navigation_depth': 3,
+	'includehidden': True,
+	'titles_only': False
+}
+
+###################################################################################################
+# Autodoc
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
+
+# Automatically extract typehints when specified and place them in
+# descriptions of the relevant function/method.
+autodoc_typehints = "description"
+
+# Don't show class signature with the class' name.
+autodoc_class_signature = "separated"
+
+autodoc_default_options = {
+ #    'members': 'var1, var2',
+    'member-order': 'bysource',
+#     'special-members': '__init__',
+    'undoc-members': True,
+#     'exclude-members': '__weakref__'
+}
+
+
+###################################################################################################
+# Napoleon, for Google docstring format
+# https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstrings
+#
+napoleon_google_docstring = True
+# napoleon_numpy_docstring = True
+napoleon_include_init_with_doc = True
+napoleon_include_private_with_doc = False
+napoleon_include_special_with_doc = True
+napoleon_use_admonition_for_examples = False
+napoleon_use_admonition_for_notes = False
+napoleon_use_admonition_for_references = False
+napoleon_use_ivar = False
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_preprocess_types = False
+napoleon_type_aliases = None
+napoleon_attr_annotations = True

docs/genindex.rst

@@ -0,0 +1,2 @@
+Index
+=====

docs/index.rst

@@ -0,0 +1,19 @@
+
+.. toctree::
+   :caption: Getting Started
+   :maxdepth: 2
+   :hidden:
+
+   overview
+   usage
+
+.. toctree::
+   :caption: Reference Documentation
+   :maxdepth: 2
+   :hidden:
+
+   api
+   genindex
+
+.. include:: overview.md
+   :parser: myst_parser.docutils_

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=.
+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