From c35f217cbe578d49d06dfc21934ca386a8708a50 Mon Sep 17 00:00:00 2001 From: David Chanin Date: Wed, 27 Dec 2023 16:45:55 -0500 Subject: [PATCH] WIP trying to get sphinx working --- docs/_static/.gitkeep | 0 docs/about.rst | 12 ++++++++ docs/api/penman_js.graph.rst | 41 +++++++++++++++++++++++++ docs/api/penman_js.rst | 58 ++++++++++++++++++++++++++++++++++++ docs/conf.py | 31 +++++++++++++++++++ docs/index.rst | 46 ++++++++++++++++++++++++++++ docs/requirements.txt | 2 ++ docs/typedoc.json | 32 ++++++++++++++++++++ package.json | 12 ++++++-- 9 files changed, 231 insertions(+), 3 deletions(-) create mode 100644 docs/_static/.gitkeep create mode 100644 docs/about.rst create mode 100644 docs/api/penman_js.graph.rst create mode 100644 docs/api/penman_js.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/requirements.txt create mode 100644 docs/typedoc.json diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/about.rst b/docs/about.rst new file mode 100644 index 0000000..a3afe74 --- /dev/null +++ b/docs/about.rst @@ -0,0 +1,12 @@ +About +========= + +This library is a manual port of the Penman Python library, with identical method names and import structure. +However, as Python and Javascript do have some differences, this port has the following changes: + +- all snake-case function names from the Python library are renamed using camel-case to fit Javascript naming conventions. For example, the function ``get_pushed_variable`` from Python is renamed to ``getPushedVariable`` in Javascript. +- Python tuples are replaced with Javascript arrays +- Python dictionaries are replaced with Javascript ``Map`` +- functions only support positional arguments, since Javascript doesn't support keyword arguments like Python +- All imports use ``penman-js`` as the base instead of ``penman``. For instance, ``from penman.graph import Graph`` in Python is replaced with ``import { Graph } from "penman-js/graph";`` in Javascript. + diff --git a/docs/api/penman_js.graph.rst b/docs/api/penman_js.graph.rst new file mode 100644 index 0000000..9273773 --- /dev/null +++ b/docs/api/penman_js.graph.rst @@ -0,0 +1,41 @@ +penman-js/graph +=============== + +.. .. autoclass:: Graph + +.. .. attribute:: top + +.. The top variable. + +.. .. attribute:: triples + +.. The list of triples that make up the graph. + +.. .. attribute:: epidata + +.. Epigraphical data that describe how a graph is to be +.. expressed when serialized. + +.. .. attribute:: metadata + +.. Metadata for the graph. + +.. .. automethod:: instances +.. .. automethod:: edges +.. .. automethod:: attributes +.. .. automethod:: variables +.. .. automethod:: reentrancies + +.. .. autoclass:: Triple + +.. .. autoattribute:: source +.. .. autoattribute:: role +.. .. autoattribute:: target + +.. .. autoclass:: Instance +.. :show-inheritance: + +.. .. autoclass:: Edge +.. :show-inheritance: + +.. .. autoclass:: Attribute \ No newline at end of file diff --git a/docs/api/penman_js.rst b/docs/api/penman_js.rst new file mode 100644 index 0000000..f9b5196 --- /dev/null +++ b/docs/api/penman_js.rst @@ -0,0 +1,58 @@ +penman-js +========= + +For basic usage, common functionality is available from the top-level +:mod:`penman-js` module. For more advanced usage, please use the full API +available via the submodules. + +Users wanting to interact with graphs might find the :func:`decode` and +:func:`encode` functions a good place to start:: + + import { encode, decode } from 'penman-js'; + const g = penman.decode('(w / want-01 :ARG0 (b / boy) :ARG1 (g / go :ARG0 b))') + console.log(g.top) + // 'w' + console.log(g.triples.length) + // 6 + console.log(g.instances().map(instance => instance[2])) + // ['want-01', 'boy', 'go'] + + // JS doesn't support keyword parameters, so `undefined` must be passed for optional params + console.log(encode(g, undefined, undefined, 'b')) + // (b / boy + // :ARG0-of (w / want-01 + // :ARG1 (g / go + // :ARG0 b))) + +The :func:`decode` and :func:`encode` functions work with one PENMAN +graph. The :func:`load` and :func:`dump` functions work with +collections of graphs. + +Users who want to work with trees would use :func:`parse` and +:func:`format` instead:: + + >>> import penman + >>> t = penman.parse('(w / want-01 :ARG0 (b / boy) :ARG1 (g / go :ARG0 b))') + >>> var, branches = t.node + >>> var + 'w' + >>> len(branches) + 3 + >>> role, target = branches[2] + >>> role + ':ARG1' + >>> print(penman.format(target)) + (g / go + :ARG0 b) + + +Classes +------- + +.. autoclass:: Tree + +.. .. autoclass:: Triple + +.. .. autoclass:: Graph + +.. .. autoclass:: PEMNANCodec \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..27200d4 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,31 @@ +# Configuration file for the Sphinx documentation builder. +# +# 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 + +project = "penman-js" +copyright = "2023, David Chanin" +author = "David Chanin" + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = ["sphinx_js"] + +js_language = "typescript" +js_source_path = "../src" +primary_domain = "js" +jsdoc_config_path = "typedoc.json" + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = "alabaster" +html_static_path = ["_static"] diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..8a2ca2f --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,46 @@ +Penman-js +===================================== + +.. image:: https://img.shields.io/npm/v/penman-js.svg?color=blue + :target: https://www.npmjs.com/package/penman-js + :alt: NPM + +.. image:: https://img.shields.io/github/actions/workflow/status/chanind/penman-js/ci.yaml?branch=main + :target: https://github.com/chanind/penman-js + :alt: Build Status + + +Javascript port of `Penman Python library `_ for Abstract Meaning Representation (AMR). + +Installation +'''''''''''' + +Penman-js can be installed from NPM + +.. code-block:: bash + + npm install penman-js + + + +.. toctree:: + :maxdepth: 2 + + Home + about + +.. toctree:: + :maxdepth: 2 + :caption: API Reference + + api/penman_js + api/penman_js.graph + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..b15a08f --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx-js @ git+https://github.com/8lurry/sphinx-js@410323b07f692e14e51c2e087b287e473dc60134 +sphinx-autobuild==2021.3.14 \ No newline at end of file diff --git a/docs/typedoc.json b/docs/typedoc.json new file mode 100644 index 0000000..e06d8fc --- /dev/null +++ b/docs/typedoc.json @@ -0,0 +1,32 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "entryPoints": ["../src/*.ts"], + "include": ["../src/**/*.ts"], + "exclude": ["../src/**/*.spec.ts"], + "compilerOptions": { + "incremental": true, + "target": "es2020", + "moduleResolution": "node", + "module": "commonjs", + "declaration": true, + "inlineSourceMap": true, + "esModuleInterop": true /* Enables emit interoperability between CommonJS and ES Modules via creation of namespace objects for all imports. Implies 'allowSyntheticDefaultImports'. */, + "resolveJsonModule": true /* Include modules imported with .json extension. */, + + /* Additional Checks */ + "noUnusedLocals": true /* Report errors on unused locals. */, + "noUnusedParameters": true /* Report errors on unused parameters. */, + "noImplicitReturns": true /* Report error when not all code paths in function return a value. */, + "noFallthroughCasesInSwitch": true /* Report errors for fallthrough cases in switch statement. */, + + /* Debugging Options */ + "traceResolution": false /* Report module resolution log messages. */, + "listEmittedFiles": false /* Print names of generated files part of the compilation. */, + "listFiles": false /* Print names of files part of the compilation. */, + "pretty": true /* Stylize errors and messages using color and context. */, + + "lib": ["es2020"], + "types": ["node"], + "typeRoots": ["../node_modules/@types", "../src/types"] + } +} diff --git a/package.json b/package.json index ab9ff3d..dcd63ae 100644 --- a/package.json +++ b/package.json @@ -48,11 +48,13 @@ "cov:send": "run-s cov:lcov && codecov", "cov:check": "nyc report && nyc check-coverage --lines 100 --functions 100 --branches 100", "doc": "run-s doc:html && open-cli build/docs/index.html", - "doc:html": "typedoc src/* --exclude **/*.spec.ts --out build/docs", - "doc:json": "typedoc src/* --exclude **/*.spec.ts --json build/docs/typedoc.json", + "doc:html": "typedoc src --out build/docs", + "doc:json": "typedoc src --json build/docs/typedoc.json", "doc:publish": "gh-pages -m \"[ci skip] Updates\" -d build/docs", "reset-hard": "git clean -dfx && git reset --hard && yarn", - "prepare-release": "run-s reset-hard test cov:check doc:html version doc:publish" + "prepare-release": "run-s reset-hard test cov:check doc:html version doc:publish", + "sphinx-build": "sphinx-build -b html docs build/docs", + "sphinx-autobuild": "sphinx-autobuild -b html docs build/docs" }, "engines": { "node": ">=10" @@ -131,6 +133,10 @@ "**/*.spec.js" ] }, + "typedocOptions": { + "entryPointStrategy": "expand", + "exclude": "**/*.spec.ts" + }, "release": { "branches": [ "main"