From 322cf8dd931a454a91274c8fbcd0784285723eb0 Mon Sep 17 00:00:00 2001 From: Remi Cattiau Date: Tue, 17 Nov 2020 14:12:40 -0800 Subject: [PATCH 1/4] fix: mismatch between tsconfig.json and typedoc.json (Close #80) --- README.rst | 5 ++++- sphinx_js/typedoc.py | 13 +++++++++---- tests/test_build_ts/source/docs/conf.py | 3 ++- tests/test_build_ts/source/typedoc.json | 3 +++ tests/testing.py | 1 + 5 files changed, 19 insertions(+), 6 deletions(-) create mode 100644 tests/test_build_ts/source/typedoc.json diff --git a/README.rst b/README.rst index b432589e..776714ae 100644 --- a/README.rst +++ b/README.rst @@ -306,7 +306,10 @@ Configuration Reference A list of directories to scan (non-recursively) for JS or TS source files, relative to Sphinx's conf.py file. Can be a string instead if there is only one. If there is more than one, ``root_for_relative_js_paths`` must be specified as well. Defaults to '../'. ``jsdoc_config_path`` - A conf.py-relative path to a JSDoc config file, which is useful if you want to specify your own JSDoc options, like recursion and custom filename matching. If using TypeDoc, you can also point to a ``tsconfig.json`` file. + A conf.py-relative path to a JSDoc config file, which is useful if you want to specify your own JSDoc options, like recursion and custom filename matching. If using TypeDoc, you can also point to a ``typedoc.json`` file. + +``jsdoc_tsconfig_path`` + If using TypeDoc, specify the path of ``tsconfig.json`` file ``root_for_relative_js_paths`` Relative JS entity paths are resolved relative to this path. Defaults to ``js_source_path`` if it is only one item. diff --git a/sphinx_js/typedoc.py b/sphinx_js/typedoc.py index 41fb1a1a..9abbd332 100644 --- a/sphinx_js/typedoc.py +++ b/sphinx_js/typedoc.py @@ -78,7 +78,8 @@ def version_to_str(t: Sequence[int]) -> str: def typedoc_output( abs_source_paths: list[str], sphinx_conf_dir: str | pathlib.Path, - config_path: str, + config_path: str | None, + tsconfig_path: str | None, base_dir: str, ) -> "Project": """Return the loaded JSON output of the TypeDoc command run over the given @@ -96,8 +97,12 @@ def typedoc_output( command.add("--entryPointStrategy", "expand") if config_path: - tsconfig_path = str((Path(sphinx_conf_dir) / config_path).absolute()) - command.add("--tsconfig", tsconfig_path) + config_path = str((Path(sphinx_conf_dir) / config_path).absolute()) + command.add("--options", config_path) + + if tsconfig_path: + tsconfig_path = str((Path(sphinx_conf_dir) / tsconfig_path).absolute()) + command.add('--tsconfig', tsconfig_path) command.add("--basePath", base_dir) @@ -311,7 +316,7 @@ def from_disk( cls, abs_source_paths: list[str], app: Sphinx, base_dir: str ) -> "Analyzer": json = typedoc_output( - abs_source_paths, app.confdir, app.config.jsdoc_config_path, base_dir + abs_source_paths, app.confdir, app.config.jsdoc_config_path, app.config.jsdoc_tsconfig_path, base_dir ) return cls( json, diff --git a/tests/test_build_ts/source/docs/conf.py b/tests/test_build_ts/source/docs/conf.py index 19ba8f72..02e389cd 100644 --- a/tests/test_build_ts/source/docs/conf.py +++ b/tests/test_build_ts/source/docs/conf.py @@ -6,7 +6,8 @@ author = "Erik Rose" exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -jsdoc_config_path = "../tsconfig.json" +jsdoc_config_path = '../typedoc.json' +jsdoc_tsconfig_path = '../tsconfig.json' js_language = "typescript" from sphinx.util import rst diff --git a/tests/test_build_ts/source/typedoc.json b/tests/test_build_ts/source/typedoc.json new file mode 100644 index 00000000..2f1ad9a6 --- /dev/null +++ b/tests/test_build_ts/source/typedoc.json @@ -0,0 +1,3 @@ +{ + "module": "modules" +} diff --git a/tests/testing.py b/tests/testing.py index 884e1430..93d616f5 100644 --- a/tests/testing.py +++ b/tests/testing.py @@ -81,6 +81,7 @@ def setup_class(cls): cls.json = typedoc_output( [join(cls._source_dir, file) for file in cls.files], cls._source_dir, + None, "tsconfig.json", cls._source_dir, ) From 9be905c1f8b9a8ecc6cc9c6f2f2ec07c51898545 Mon Sep 17 00:00:00 2001 From: David Brooks Date: Tue, 30 Apr 2024 11:44:11 +1200 Subject: [PATCH 2/4] Add default config value for `jsdoc_tsconfig_path` (fixes PR #116). --- sphinx_js/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx_js/__init__.py b/sphinx_js/__init__.py index 0636623f..76c3aee9 100644 --- a/sphinx_js/__init__.py +++ b/sphinx_js/__init__.py @@ -176,6 +176,7 @@ def setup(app: Sphinx) -> None: "js_source_path", default=["../"], rebuild="env", types=[str, list] ) app.add_config_value("jsdoc_config_path", default=None, rebuild="env") + app.add_config_value("jsdoc_tsconfig_path", default=None, rebuild="env") app.add_config_value("ts_type_xref_formatter", None, "env") app.add_config_value("ts_type_bold", False, "env") app.add_config_value("ts_should_destructure_arg", None, "env") From 35b1705583fb9d1a24471ba68b59102e17ddab20 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 29 Apr 2024 23:59:28 +0000 Subject: [PATCH 3/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- sphinx_js/typedoc.py | 8 ++++++-- tests/test_build_ts/source/docs/conf.py | 4 ++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/sphinx_js/typedoc.py b/sphinx_js/typedoc.py index 5eb91b2c..6bce131e 100644 --- a/sphinx_js/typedoc.py +++ b/sphinx_js/typedoc.py @@ -105,7 +105,7 @@ def typedoc_output( if tsconfig_path: tsconfig_path = str((Path(sphinx_conf_dir) / tsconfig_path).absolute()) - command.add('--tsconfig', tsconfig_path) + command.add("--tsconfig", tsconfig_path) command.add("--basePath", base_dir) @@ -319,7 +319,11 @@ def from_disk( cls, abs_source_paths: list[str], app: Sphinx, base_dir: str ) -> "Analyzer": json = typedoc_output( - abs_source_paths, app.confdir, app.config.jsdoc_config_path, app.config.jsdoc_tsconfig_path, base_dir + abs_source_paths, + app.confdir, + app.config.jsdoc_config_path, + app.config.jsdoc_tsconfig_path, + base_dir, ) return cls( json, diff --git a/tests/test_build_ts/source/docs/conf.py b/tests/test_build_ts/source/docs/conf.py index 02e389cd..748a4140 100644 --- a/tests/test_build_ts/source/docs/conf.py +++ b/tests/test_build_ts/source/docs/conf.py @@ -6,8 +6,8 @@ author = "Erik Rose" exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] -jsdoc_config_path = '../typedoc.json' -jsdoc_tsconfig_path = '../tsconfig.json' +jsdoc_config_path = "../typedoc.json" +jsdoc_tsconfig_path = "../tsconfig.json" js_language = "typescript" from sphinx.util import rst From f25f6006999d1ab8bf471e63fe7a8d23a644e976 Mon Sep 17 00:00:00 2001 From: Hood Chatham Date: Thu, 2 May 2024 14:55:28 +0200 Subject: [PATCH 4/4] Improve the names of typedoc_output args and fix test again --- sphinx_js/typedoc.py | 27 ++++++++++++++----------- tests/test_build_ts/source/typedoc.json | 4 +--- tests/testing.py | 12 +++++------ 3 files changed, 22 insertions(+), 21 deletions(-) diff --git a/sphinx_js/typedoc.py b/sphinx_js/typedoc.py index 333f4ff8..01ea597f 100644 --- a/sphinx_js/typedoc.py +++ b/sphinx_js/typedoc.py @@ -49,11 +49,11 @@ def version_to_str(t: Sequence[int]) -> str: def typedoc_output( abs_source_paths: Sequence[str], + base_dir: str, sphinx_conf_dir: str | pathlib.Path, - config_path: str | None, + typedoc_config_path: str | None, tsconfig_path: str | None, - base_dir: str, - config_file: str | None, + ts_sphinx_js_config: str | None, ) -> list[ir.TopLevelUnion]: """Return the loaded JSON output of the TypeDoc command run over the given paths.""" @@ -71,13 +71,15 @@ def typedoc_output( dir = Path(__file__).parent.resolve() / "js" command.add("--import", str(dir / "registerImportHook.mjs")) command.add(str(dir / "call_typedoc.ts")) - if config_file: - command.add("--sphinx-js-config", config_file) + if ts_sphinx_js_config: + command.add("--sphinx-js-config", ts_sphinx_js_config) command.add("--entryPointStrategy", "expand") - if config_path: - config_path = str((Path(sphinx_conf_dir) / config_path).absolute()) - command.add("--options", config_path) + if typedoc_config_path: + typedoc_config_path = str( + (Path(sphinx_conf_dir) / typedoc_config_path).absolute() + ) + command.add("--options", typedoc_config_path) if tsconfig_path: tsconfig_path = str((Path(sphinx_conf_dir) / tsconfig_path).absolute()) @@ -130,10 +132,11 @@ def from_disk( ) -> "Analyzer": json = typedoc_output( abs_source_paths, - app.confdir, - app.config.jsdoc_config_path, - app.config.jsdoc_tsconfig_path, - base_dir, + base_dir=base_dir, + sphinx_conf_dir=app.confdir, + typedoc_config_path=app.config.jsdoc_config_path, + tsconfig_path=app.config.jsdoc_tsconfig_path, + ts_sphinx_js_config=app.config.ts_sphinx_js_config, ) return cls(json, base_dir) diff --git a/tests/test_build_ts/source/typedoc.json b/tests/test_build_ts/source/typedoc.json index 2f1ad9a6..0967ef42 100644 --- a/tests/test_build_ts/source/typedoc.json +++ b/tests/test_build_ts/source/typedoc.json @@ -1,3 +1 @@ -{ - "module": "modules" -} +{} diff --git a/tests/testing.py b/tests/testing.py index c741cb92..8949e12a 100644 --- a/tests/testing.py +++ b/tests/testing.py @@ -83,12 +83,12 @@ def setup_class(cls): config_file = Path(__file__).parent / "sphinxJsConfig.ts" cls.json = typedoc_output( - [join(cls._source_dir, file) for file in cls.files], - cls._source_dir, - None, - "tsconfig.json", - cls._source_dir, - str(config_file), + abs_source_paths=[join(cls._source_dir, file) for file in cls.files], + base_dir=cls._source_dir, + ts_sphinx_js_config=str(config_file), + typedoc_config_path=None, + tsconfig_path="tsconfig.json", + sphinx_conf_dir=cls._source_dir, )