Documentation (#1)

* docs

* Basic docs

* Documentation, bugfix

* delete reference

* Defining objects

* Reducing example

* Parameter validation

* Annotations docs

* Finish writing docs

Author: davidhozic

.gitignore

@@ -70,6 +70,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/reference/
 
 # PyBuilder
 .pybuilder/

MANIFEST.in

@@ -0,0 +1 @@
+graft tkclasswiz

README.rst

@@ -1,18 +1,45 @@
-=================
+=========================================================
 TkClassWizard
-=================
+=========================================================
+TkClassWizard - define objects graphically based on class annotations.
+The library allows users to create abstract "ObjectInfo" objects based on the class's parameters, which
+can later be converted to real Python objects and vice versa.
 
-Library for graphically defining objects based on class annotations.
-Works with Tkinter / TTKBootstrap
+---------------------
+Links
+---------------------
+- `Releases <https://github.com/davidhozic/TkClassWizard/releases>`_
+- Need help? Contact me in my `Discord server <https://discord.gg/DEnvahb2Sw>`_.
 
+----------------------
+Installation
+----------------------
+DAF can be installed though command prompt/terminal using the bottom commands.
+        
+Pre-requirement: `Python (minimum v3.8) <https://www.python.org/downloads/>`_
+
+
+.. code-block:: bash
+
+    pip install tkclasswiz
+
+----------------------
 Example
-============
+----------------------
+
+.. image:: guide/images/new_define_frame_struct_new_str.png
+    :width: 15cm
 
 .. code-block:: python
+    :linenos:
+    :emphasize-lines: 11-15, 31-32
 
+    import tkinter as tk
+    import tkinter.ttk as ttk
     import tkclasswiz as wiz
 
 
+    # Normal Python classes with annotations (type hints)
     class Wheel:
         def __init__(self, diameter: float):
             self.diameter = diameter
@@ -23,7 +50,31 @@ Example
             self.speed = speed
             self.wheels = wheels
 
+    # Tkinter main window
+    root = tk.Tk("Test")
+
+    # Modified tkinter Combobox that will store actual objects instead of strings
+    combo = wiz.ComboBoxObjects(root)
+    combo.pack(fill=tk.X, padx=5)
+
+    def make_car(old = None):
+        """
+        Function for opening a window either in new definition mode (old = None) or
+        edit mode (old != None)
+        """
+        assert old is None or isinstance(old, wiz.ObjectInfo)
+
+        window = wiz.ObjectEditWindow()  # The object definition window / wizard
+        window.open_object_edit_frame(Car, combo, old_data=old)  # Open the actual frame
+
+    def print_defined():
+        data = combo.get()
+        data = wiz.convert_to_objects(data)  # Convert any abstract ObjectInfo objects into actual Python objects
+        print(f"Object: {data}; Type: {type(data)}",)  # Print the object and it's datatype
+
 
-    combo = wiz.ComboBoxObjects()
-    window = ObjectEditWindow()
-    window.open_object_edit_frame(Car, combo)
+    # Main GUI structure
+    ttk.Button(text="Define Car", command=make_car).pack()
+    ttk.Button(text="Edit Car", command=lambda: make_car(combo.get())).pack()
+    ttk.Button(text="Print defined", command=print_defined).pack()
+    root.mainloop()

docs/Makefile

@@ -0,0 +1,47 @@
+# 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
+USE_LANGUAGE  ?= sl
+
+export LANGUAGE=$(USE_LANGUAGE)
+
+_BUILD_DIR = $(BUILDDIR)/$(SOURCEDIR)
+
+# OS specific commands
+ifeq ($(OS), Windows_NT)
+LATEX_CMD := \
+	cp $(CURDIR)/build-latex-win.sh $(CURDIR)/$(_BUILD_DIR)/latex/ &&\
+	wsl --cd $(CURDIR)/$(_BUILD_DIR)/latex sh build-latex-win.sh
+
+else
+LATEX_CMD := cd $(CURDIR)/$(_BUILD_DIR)/latex && make all-pdf
+endif
+
+
+# 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).
+
+clean:
+	python3 ./setup.py --clean --start-dir $(SOURCEDIR)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(_BUILD_DIR)" $(SPHINXOPTS) $(O)
+
+pdf: latex
+	mkdir -p $(CURDIR)/$(_BUILD_DIR)/pdf/
+	$(LATEX_CMD)
+	cp $(CURDIR)/$(_BUILD_DIR)/latex/*.pdf $(CURDIR)/$(_BUILD_DIR)/pdf/
+
+%: Makefile
+	python3 ./setup.py --start-dir $(SOURCEDIR)
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(_BUILD_DIR)" $(SPHINXOPTS) $(O)

docs/build-latex-win.sh

@@ -0,0 +1,21 @@
+# Script is created to speed up the latex compilation on the windows system though wsl.
+# It copis all latex files to a wsl directory, runs the latex compiler and then copies them back
+# to the orignal path.
+
+ORIGIN_DIR=$(pwd)
+LATEX_BUILD_PATH=~/latex-build/
+
+# Copy the current folder (latex build folder) contents to our home folder
+echo Creating dir $LATEX_BUILD_PATH
+mkdir -p $LATEX_BUILD_PATH
+
+echo Copying files to $LATEX_BUILD_PATH
+cp -r $ORIGIN_DIR/** $LATEX_BUILD_PATH
+
+echo Building latex
+cd $LATEX_BUILD_PATH
+make all-pdf
+cp -r $LATEX_BUILD_PATH/** $ORIGIN_DIR
+
+echo Cleaning up $LATEX_BUILD_PATH
+rm -rf $LATEX_BUILD_PATH

docs/dep_local.json

@@ -0,0 +1,4 @@
+{
+    "copy": [],
+    "scripts": []
+}

docs/setup.py

@@ -0,0 +1,72 @@
+"""
+Script that setups the environment before build.
+"""
+
+from pathlib import Path
+from argparse import ArgumentParser
+
+import runpy
+import re
+import os
+import glob
+import shutil
+import json
+
+
+parse = ArgumentParser()
+parse.add_argument("--clean", action="store_true", default=False, help="If given, it will only clean instead of copy and run")
+parse.add_argument("--start-dir", default="./", dest="start_dir", help="Where to start looking for dep_local.json")
+args = parse.parse_args()
+
+
+CLEAN_ARG: bool = args.clean
+START_DIR_ARG: str = args.start_dir
+
+# Work relatively to the setup script location
+os.chdir(os.path.dirname(__file__))
+
+for path, dirs, files in os.walk(START_DIR_ARG):
+    for file in files:
+        if file == "dep_local.json":
+            file = os.path.join(path, file)
+            # Copy files
+            setup_file_data: dict = None
+            with open(file, 'r', encoding="utf-8") as setup_file:
+                setup_file_data = json.load(setup_file)
+
+            # While copying change to dep-files cwd
+            cwd = os.getcwd()
+            os.chdir(os.path.abspath(os.path.dirname(file)))
+            # [(from, to), (from, to)]
+            destinations = setup_file_data["copy"]
+            for dest in destinations:
+                cp_from = dest["from"]
+                cp_to = dest["to"]
+                if re.search(r"\.[A-z]+$", cp_to) is None:  # The path does not have extension -> assume a dir
+                    _src = [x for x in glob.glob(cp_from, recursive=True) if os.path.isfile(x)]
+                    _dest = [os.path.join(cp_to, os.path.basename(m)) for m in _src]
+                else:
+                    _src = [cp_from]
+                    _dest = [cp_to]
+
+                srcdest = zip(_src, _dest)
+                for fromf, tof in srcdest:
+                    if CLEAN_ARG:
+                        if os.path.exists(tof):
+                            os.remove(tof)
+                    else:
+                        tof_dir = Path(os.path.dirname(tof))
+                        tof_dir.mkdir(parents=True, exist_ok=True)
+                        shutil.copy2(fromf, tof)
+
+            # Run scripts
+            if CLEAN_ARG:
+                os.chdir(cwd)
+                continue
+
+            scripts = setup_file_data["scripts"]
+            for script in scripts:
+                runpy.run_path(script)
+
+            # Change cwd back to original
+            os.chdir(cwd)

docs/source/conf.py

@@ -0,0 +1,107 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# 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 sys
+import os
+
+os.environ["DOCUMENTATION"] = "True"
+sys.path.insert(0, os.path.abspath('../../src/'))
+sys.path.insert(0, os.path.abspath('.'))
+
+from tkclasswiz import __version__
+
+
+# -- Project information -----------------------------------------------------
+project = 'TkClassWizard'
+copyright = '2023, David Hozic'
+author = 'David Hozic'
+version = __version__
+
+
+# -- General configuration ---------------------------------------------------
+root_doc = 'index'
+
+numfig = True
+
+# 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.napoleon",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "enum_tools.autoenum",
+    "sphinx_design",
+    "sphinx_search.extension",
+    "sphinxcontrib.inkscapeconverter"
+]
+
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.txt': 'markdown',
+    '.md': 'markdown',
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# Autodoc
+autodoc_typehints = "signature"
+autodoc_typehints_format = "short"
+
+
+developement_build = os.environ.get("DOC_DEVELOPMENT", default="False")
+developement_build = True if developement_build == "True" else False
+
+autodoc_default_options = {
+    'member-order': 'bysource',
+    "private-members": developement_build
+}
+
+
+# Intersphinx
+intersphinx_mapping = {
+    "Python" : ("https://docs.python.org/3/", None)
+}
+
+# ----------- HTML ----------- #
+html_title = project
+html_theme = 'furo'
+html_static_path = ['_static']
+html_theme_options = {
+    "navigation_with_keys": True,
+    "top_of_page_button": "edit",
+    "source_repository": "https://github.com/davidhozic/TkClassWizard",
+    "source_branch": "develop",
+    "source_directory": "docs/source",
+    "footer_icons": [
+        {
+            "name": "GitHub",
+            "url": "https://github.com/davidhozic/TkClassWizard",
+            "html": '<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path></svg>',
+            "class": "",
+        }
+    ],
+}
+
+# ----------- Latex ----------- #
+

docs/source/dep_local.json

@@ -0,0 +1,5 @@
+{
+    "copy": [
+    ],
+    "scripts": ["./scripts/generate_autodoc.py"]
+}