WIP trying to get sphinx working

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

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

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

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"]

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 <https://github.com/goodmami/penman>`_ for Abstract Meaning Representation (AMR).
+
+Installation
+''''''''''''
+
+Penman-js can be installed from NPM
+
+.. code-block:: bash
+
+    npm install penman-js
+
+
+
+.. toctree::
+   :maxdepth: 2
+
+   Home <self>
+   about
+
+.. toctree::
+   :maxdepth: 2
+   :caption: API Reference
+
+   api/penman_js
+   api/penman_js.graph
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx-js @ git+https://github.com/8lurry/sphinx-js@410323b07f692e14e51c2e087b287e473dc60134
+sphinx-autobuild==2021.3.14

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"]
+  }
+}

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"