Merge pull request #127 from IanCa/dev_docs_final

Initial pass of javascript docs

common/schema/types.js

@@ -61,6 +61,9 @@ export class Schema {
   tagHasAttribute(tag, tagAttribute) {}
 }
 
+/**
+ * Hed2Schema class
+ */
 export class Hed2Schema extends Schema {
   /**
    * The description of tag attributes.
@@ -91,6 +94,9 @@ export class Hed2Schema extends Schema {
   }
 }
 
+/**
+ * Hed3Schema class
+ */
 export class Hed3Schema extends Schema {
   /**
    * The collection of schema entries.

converter/splitHedString.js

@@ -7,7 +7,7 @@ const tagDelimiters = new Set([',', '(', ')', '~'])
  * @returns {Array[]} A list of string parts. The boolean is true if the part is
  * a tag and false if it is a delimiter. The numbers are the bounds of the part.
  */
-export default function splitHedString(hedString) {
+export function splitHedString(hedString) {
   const resultPositions = []
   let currentSpacing = 0
   let insideDelimiter = true
@@ -62,3 +62,5 @@ export default function splitHedString(hedString) {
 
   return resultPositions
 }
+
+export default splitHedString

docs/Makefile

@@ -1,5 +1,26 @@
-# Minimal makefile for Sphinx documentation
-#
+# We avoid $(CURDIR) because it spits out /cygdrive/c/... on Windows Cygwin
+# installs and leads to things that don't work.
+VIRTUAL_ENV = venv
+PYTHON3 ?= python3
+
+# Let us find jsdoc and sphinx:
+export PATH := node_modules/.bin:$(VIRTUAL_ENV)/bin:$(VIRTUAL_ENV)/Scripts:$(PATH)
+
+# I'm not entirely sure why this line is needed yet...
+.PHONY: js
+
+# Verify venv exists
+.PHONY: venv
+venv: $(VIRTUAL_ENV)/pyvenv.cfg
+
+$(VIRTUAL_ENV)/pyvenv.cfg:
+	$(PYTHON3) -m venv $(VIRTUAL_ENV)
+	PATH="$(PATH)" pip3 install -r requirements.txt
+
+# Not sure if this is needed...
+# .npm_installed: ../package.json
+# 	npm install
+# 	touch $@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
@@ -18,3 +39,12 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+
+
+# Delete just the built docs, not the whole venv, which is expensive to
+# reconstitute:
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)
+	rm -rf node_modules .npm_installed

docs/source/bids.rst

@@ -0,0 +1,13 @@
+bids
+====
+
+Bids functionality
+
+.. toctree::
+   :maxdepth: 8
+
+   bids.schema.rst
+   bids.tsvParser.rst
+   bids.types.rst
+   bids.utils.rst
+   bids.validate.rst

docs/source/api2.rst → docs/source/bids.schema.rst

@@ -1,3 +1,4 @@
-HED API reference (Auto style)
+Schema
 ==============================
 
+Intentionally Blank

docs/source/bids.tsvParser.rst

@@ -0,0 +1,5 @@
+tsvParse
+==============================
+
+.. js:autofunction:: parseTSV
+

docs/source/bids.types.rst

@@ -0,0 +1,23 @@
+types
+==============================
+
+.. js:autoclass:: BidsData
+    :members:
+
+.. js:autoclass:: BidsFile
+    :members:
+
+.. js:autoclass:: BidsJsonFile
+    :members:
+
+.. js:autoclass:: BidsTsvFile
+    :members:
+
+.. js:autoclass:: BidsEventFile
+    :members:
+
+.. js:autoclass:: BidsTabularFile
+    :members:
+
+.. js:autoclass:: BidsSidecar
+    :members:

docs/source/bids.utils.rst

@@ -0,0 +1,5 @@
+utils
+==============================
+
+.. js:autofunction:: sidecarValueHasHed
+

docs/source/bids.validate.rst

@@ -0,0 +1,22 @@
+validate
+==============================
+
+.. js:autofunction:: sidecarValueHasHed
+
+.. js:autofunction:: validateBidsDataset
+
+.. js:autofunction:: validateFullDataset
+
+.. js:autofunction:: validateBidsTsvFile
+
+.. js:autofunction:: validateSidecars
+
+.. js:autofunction:: validateHedColumn
+
+.. js:autofunction:: parseTsvHed
+
+.. js:autofunction:: validateCombinedDataset
+
+.. js:autofunction:: validateStrings
+
+.. js:autofunction:: convertHedIssuesToBidsIssues

docs/source/common.issues.data.rst

@@ -0,0 +1,4 @@
+data
+======
+
+Intentionally blank for now

docs/source/common.issues.issues.rst

@@ -0,0 +1,8 @@
+issues
+======
+
+.. js:autoclass:: Issue
+    :members:
+
+.. js:autofunction:: generateIssue
+

docs/source/common.issues.rst

@@ -0,0 +1,8 @@
+issues
+======
+
+.. toctree::
+   :maxdepth: 8
+
+   common.issues.issues
+   common.issues.data

docs/source/common.rst

@@ -0,0 +1,8 @@
+common
+======
+
+.. toctree::
+   :maxdepth: 8
+
+   common.schema
+   common.issues

docs/source/common.schema.config.rst

@@ -0,0 +1,4 @@
+config
+======
+
+Intentionally blank for now

docs/source/common.schema.loader.rst

@@ -0,0 +1,18 @@
+loader
+======
+
+.. js:autofunction:: loadSchema
+
+.. js:autofunction:: loadSchemaFromSpec
+
+.. js:autofunction:: loadPromise
+
+.. js:autofunction:: loadRemoteSchema
+
+.. js:autofunction:: loadLocalSchema
+
+.. js:autofunction:: loadBundledSchema
+
+.. js:autofunction:: loadSchemaFile
+
+.. js:autofunction:: parseSchemaXML

docs/source/common.schema.rst

@@ -0,0 +1,9 @@
+schema
+======
+
+.. toctree::
+   :maxdepth: 8
+
+   common.schema.types
+   common.schema.loader
+   common.schema.config

docs/source/common.schema.types.rst

@@ -0,0 +1,20 @@
+types
+======
+
+.. js:autoclass:: Schema
+    :members:
+
+.. js:autoclass:: Hed2Schema
+    :members:
+
+.. js:autoclass:: Hed3Schema
+    :members:
+
+.. js:autoclass:: Schemas
+    :members:
+
+.. js:autoclass:: SchemaSpec
+    :members:
+
+.. js:autoclass:: SchemasSpec
+    :members:

docs/source/conf.py

@@ -14,7 +14,7 @@
 import sys
 import sphinx_rtd_theme
 from datetime import date
-import subprocess
+
 
 sys.path.insert(0, os.path.abspath('../../../'))
 
@@ -42,30 +42,29 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    "myst_parser",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.autosectionlabel",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.coverage",
-    "sphinx.ext.mathjax",
-    "sphinx.ext.viewcode",
-    "sphinx.ext.githubpages",
-    "sphinx.ext.napoleon",
-    "sphinx.ext.extlinks",
-    "sphinx_js"
+    #     'sphinx.ext.autodoc',
+    #     'sphinx.ext.viewcode',
+    # 'sphinx_click.ext',
+    'sphinx_js'
 ]
 
-js_source_path = '../../'
+root_for_relative_js_paths = "../../"
+base_folders = ["../../bids", "../../validator", "../../converter", "../../common", "../../utils"]
 
-primary_domain = 'js'
+def find_all_folders(directory):
+    all_folders = [directory]
+
+    for root, dirs, _ in os.walk(directory):
+        for d in dirs:
+            all_folders.append(os.path.join(root, d))
 
-autosummary_generate = True
-autodoc_default_flags = ['members', 'inherited-members']
-add_module_names = False
-myst_all_links_external = False
-myst_heading_anchors = 2
-myst_enable_extensions = ["deflist"]
+    return all_folders
+
+js_source_path = []
+for folder in base_folders:
+    js_source_path += find_all_folders(folder)
+print(js_source_path)
+primary_domain = 'js'
 
 
 # Add any paths that contain templates here, relative to this directory.
@@ -76,7 +75,7 @@
 # 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 = ['_build', '_templates', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ['_build', '_templates', 'Thumbs.db', '.DS_Store', 'venv']
 
 
 # -- Options for HTML output -------------------------------------------------
@@ -100,29 +99,14 @@
     # Toc options
     'collapse_navigation': False,
     'sticky_navigation': True,
-    'navigation_depth': 4,
+    'navigation_depth': 6,
     'includehidden': True,
     'titles_only': False
 }
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
-
-
-def run_jsdoc(app):
-    source_dir = app.builder.srcdir
-    jsdoc_output_dir = os.path.join(source_dir, 'jsdoc_output')
-    jsdoc_command = [
-        'npx',  # Use npx to run locally installed npm packages
-        'jsdoc',
-        '-c', os.path.join(source_dir, 'path/to/jsdoc/config.json'),  # Adjust the path to your JSDoc config
-        '-d', jsdoc_output_dir,
-        'path/to/javascript/files',  # Adjust the path to your JavaScript files
-    ]
-    subprocess.call(jsdoc_command)
-
+import sphinx_rtd_theme
+html_static_path = [os.path.join(sphinx_rtd_theme.get_html_theme_path(), 'sphinx_rtd_theme', 'static')]
 
-def setup(app):
-    app.connect('builder-inited', run_jsdoc)
 

docs/source/converter.converter.rst

@@ -0,0 +1,18 @@
+converter
+=========
+
+.. js:autofunction:: removeSlashesAndSpaces
+
+.. js:autofunction:: convertTagToLong
+
+.. js:autofunction:: convertTagToShort
+
+.. js:autofunction:: convertPartialHedStringToLong
+
+.. This one is not marked for export
+ .. js:autofunction:: convertHedString
+
+.. js:autofunction:: convertHedStringToLong
+
+.. js:autofunction:: convertHedStringToShort
+

docs/source/converter.issues.rst

@@ -0,0 +1,4 @@
+issues
+======
+
+Intentionally blank for now

docs/source/converter.rst

@@ -0,0 +1,11 @@
+converter
+=========
+
+.. toctree::
+   :maxdepth: 8
+
+   converter.types
+   converter.schema
+   converter.issues
+   converter.splitHedString
+   converter.converter

docs/source/converter.schema.rst

@@ -0,0 +1,7 @@
+schema
+=========
+
+.. js:autofunction:: buildMappingObject
+
+.. js:autofunction:: schema.buildSchema
+