From 5a7c25cbcc302949843381c657d006f30c464a00 Mon Sep 17 00:00:00 2001 From: Neil Johnson Date: Mon, 18 Sep 2023 11:11:54 -0400 Subject: [PATCH] doc api reference Signed-off-by: Neil Johnson --- .github/workflows/mkdocs-build.yml | 3 +- .github/workflows/pipeline.yml | 5 +- docs/ati-compat.md | 7 ++ docs/ati.md | 6 ++ docs/index.md | 29 ++------ docs/tnz.md | 2 + docs/zti.md | 7 ++ mkdocs.yml | 30 +++++++- requirements.txt | 15 ++-- tnz/ati.py | 109 ++++++++++++++--------------- tnz/zti.py | 4 +- 11 files changed, 125 insertions(+), 92 deletions(-) create mode 100644 docs/ati-compat.md create mode 100644 docs/ati.md create mode 100644 docs/tnz.md create mode 100644 docs/zti.md diff --git a/.github/workflows/mkdocs-build.yml b/.github/workflows/mkdocs-build.yml index 137b944..f1da868 100644 --- a/.github/workflows/mkdocs-build.yml +++ b/.github/workflows/mkdocs-build.yml @@ -2,7 +2,6 @@ name: mkdocs-build on: push: branches: - - master - main jobs: deploy: @@ -12,5 +11,5 @@ jobs: - uses: actions/setup-python@v2 with: python-version: 3.x - - run: pip install mkdocs-material mkdocs-minify-plugin + - run: pip install --disable-pip-version-check -r requirements.txt - run: mkdocs gh-deploy --force diff --git a/.github/workflows/pipeline.yml b/.github/workflows/pipeline.yml index 3813b20..55ca018 100644 --- a/.github/workflows/pipeline.yml +++ b/.github/workflows/pipeline.yml @@ -18,8 +18,7 @@ jobs: - name: Install dependencies run: | - pip install wheel - if [ -f requirements.txt ]; then pip install -r requirements.txt; fi + pip install --disable-pip-version-check -r requirements.txt - name: Lint run: | @@ -44,7 +43,7 @@ jobs: - name: Install dependencies run: | - pip install wheel build twine + pip install --disable-pip-version-check -r requirements.txt - name: Build dist run: | diff --git a/docs/ati-compat.md b/docs/ati-compat.md new file mode 100644 index 0000000..cebb016 --- /dev/null +++ b/docs/ati-compat.md @@ -0,0 +1,7 @@ +# ati (compatability) +::: tnz.ati + options: + filters: + - "!^_" + - "!^Ati" + group_by_category: false diff --git a/docs/ati.md b/docs/ati.md new file mode 100644 index 0000000..cdddbca --- /dev/null +++ b/docs/ati.md @@ -0,0 +1,6 @@ +# ati +::: tnz.ati + options: + members: + - "ati" + - "Ati" diff --git a/docs/index.md b/docs/index.md index 2117b38..ab0298c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,22 +2,12 @@ title: Introduction --- -Use a standard terminal emulator as a 3270 terminal interface. - -Write -scripts to automate 3270 terminal interaction. - -This is both a 3270 -terminal emulator and a Python libary. - -The zti module provides a 3270 +Use a standard terminal emulator as a 3270 terminal interface. Write +scripts to automate 3270 terminal interaction. This is both a 3270 +terminal emulator and a Python libary. The zti module provides a 3270 user interface through a Windows Command Prompt or a unix/ascii -terminal. - -The tnz module handles the interface to the 3270 data -stream. - -The ati module allows for easier 3270 terminal automation. +terminal. The tnz module handles the interface to the 3270 data +stream. The ati module allows for easier 3270 terminal automation. #### Features * Runs on many platforms (including z/OS) @@ -109,10 +99,6 @@ select text. Once the text is selected, press Enter to copy the text.** There are other ways to select text, but I this to be the easiest. -Do NOT use Control-menu->Edit->Paste to paste text (unless the -text in the clipboard has ONLY printable characters - no line -breaks). Instead, **use Shift+Insert to paste**. - Before establishing a session, get the window sized the way you want it. Window resizing is not handled well in Windows. If you _do_ resize, just use Esc to get to the command prompt then `goto` to get @@ -123,11 +109,6 @@ terminal. The character size and font can be set. I recommend **Lucida Console** - it is readable and the graphic symbols are fairly good at connecting like they are supposed to. - -## Documentation - -For additional details, see docstrings in source code. - ## Contributing See [CONTRIBUTING.md](https://github.com/IBM/tnz/blob/main/CONTRIBUTING.md). diff --git a/docs/tnz.md b/docs/tnz.md new file mode 100644 index 0000000..5d812cc --- /dev/null +++ b/docs/tnz.md @@ -0,0 +1,2 @@ +# tnz +::: tnz.tnz diff --git a/docs/zti.md b/docs/zti.md new file mode 100644 index 0000000..bfe7cd5 --- /dev/null +++ b/docs/zti.md @@ -0,0 +1,7 @@ +# zti +::: tnz.zti + options: + group_by_category: false + members: + - "create" + - "main" diff --git a/mkdocs.yml b/mkdocs.yml index 8426c02..eadebb2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,3 +1,13 @@ +nav: + - Introduction: index.md + - Colors: colors.md + - Screen Sizing: screen-sizing.md + - Security: security.md + - API Reference: + - ati: ati.md + - ati (compatability): ati-compat.md + - tnz: tnz.md + - zti: zti.md site_name: Tn3270 to Z Python library site_url: https://ibm.github.io/tnz repo_url: https://github.com/IBM/tnz/ @@ -5,6 +15,8 @@ edit_uri: edit/main/docs/ # required for GHE, theme will not do Enterprise autom # Theme theme: name: material + features: + - navigation.expand palette: - primary: default toggle: @@ -21,13 +33,27 @@ theme: # Plugins plugins: - search + - mkdocstrings: + handlers: + python: + options: + filters: + - "!^_" + inherited_members: true + separate_signature: true + show_category_heading: true + show_root_toc_entry: false + show_source: false + show_symbol_type_heading: true + show_symbol_type_toc: true + show_if_no_docstring: true - minify: minify_html: true # Markdown extensions markdown_extensions: - markdown.extensions.toc: - slugify: !!python/name:pymdownx.slugs.uslugify + slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}} permalink: ยง - markdown.extensions.admonition: - markdown.extensions.smarty: @@ -63,4 +89,4 @@ markdown_extensions: - pymdownx.details: - pymdownx.tabbed: -copyright: Copyright © IBM 2022 +copyright: Copyright © IBM 2022, 2023 diff --git a/requirements.txt b/requirements.txt index 5dd1b3c..33045a7 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,4 +1,11 @@ -ebcdic -pycodestyle -pylint -pytest +black >= 23.3.0; python_version >= "3.8" +build >= 1.0.3 +ebcdic >= 1.1.1; sys_platform != "zos" +mkdocs-material >= 9.2.8; python_version >= "3.8" +mkdocs-minify-plugin >= 0.7.1; python_version >= "3.8" +mkdocstrings-python >= 1.1.2; python_version >= "3.8" +pycodestyle >= 2.10.0 +pylint >= 2.17.5 +pytest >= 7.4.2 +twine >= 4.0.2; sys_platform != "zos" +wheel >= 0.41.2 diff --git a/tnz/ati.py b/tnz/ati.py index 922d930..2a7f186 100644 --- a/tnz/ati.py +++ b/tnz/ati.py @@ -156,18 +156,18 @@ class Ati(): Automate a set of 3270 terminal sessions. Methods with ATI function equivalents: - drop - extract - logwrt - num - say - scrhas - send - set - share - value - wait - when + - drop + - extract + - logwrt + - num + - say + - scrhas + - send + - set + - share + - value + - wait + - when Methods from tnz.rexx with ATI function equivalents: copies @@ -181,50 +181,49 @@ class Ati(): words Methods from Python with ATI function equivalents: - stripl - stript - upper + - stripl + - stript + - upper ATI functions with no equivalent method implemented: - chr - cms - include - keywait - ord - pull - push + - chr + - cms + - include + - keywait + - ord + - pull + - push Properties with internal ATI variable equivalents: - age - curcol - currow - date - datetime - display - hitcol - hitrow - hitstr - keylock - keyunlock - logdest - maxcol - maxrow - maxlostwarn - maxwait - milliage - onerror - rc - sendstr - seslost - session - sessionid - sessions - session24 - showline - showtype - time - trace - waitsleep + - curcol + - currow + - date + - datetime + - display + - hitcol + - hitrow + - hitstr + - keylock + - keyunlock + - logdest + - maxcol + - maxrow + - maxlostwarn + - maxwait + - milliage + - onerror + - rc + - sendstr + - seslost + - session + - sessionid + - sessions + - session24 + - showline + - showtype + - time + - trace + - waitsleep """ # dunder methods @@ -2818,8 +2817,8 @@ def date(self): def datetime(self): """Current Date/Time - Contains the current date and time in the form yy/mm/dd - hh:mm:ss. To get the date in yyyy/mm/dd hh:mm:ss form, set + Contains the current date and time in the form `yy/mm/dd + hh:mm:ss`. To get the date in `yyyy/mm/dd hh:mm:ss` form, set the DATEFORM environment variable to LONG (in any case). """ if self.__century(): @@ -2925,7 +2924,7 @@ def sessions(self): def time(self): """Current Time - Contains the current time in the form hh:mm:ss. + Contains the current time in the form `hh:mm:ss`. """ return time.strftime("%H:%M:%S") diff --git a/tnz/zti.py b/tnz/zti.py index c4b684f..961bb04 100644 --- a/tnz/zti.py +++ b/tnz/zti.py @@ -1,7 +1,7 @@ """Z terminal interface Like ATI Session Manager. - +``` Command usage: zti [-h] [--nolog] [--noztirc | --rcfile rcfile] [host] @@ -13,7 +13,7 @@ --nolog Do not set LOGDEST to zti.log --noztirc Do not SOURCE .ztirc in home directory --rcfile rcfile Filename to run using SOURCE - +``` Create a command plugin by creating a "zti.commands" entry point through setup.py that takes a single argument of a command line string.