Feature: Support specifying which element to include in the docs.

[adaxi]

This is a follow up of the discussion held in issue 21.

At the moment mkdocsstrings-typescript only supports exporting the full package. (i.e ::: @package)

In the python version of the library it seems to be possible to display only information about a specific class.

# Reference

::: my_library.my_module.my_class

I maintain a large package, so including the whole package documentation in a single page does not make it very easy to read. I would like to cherry pick relevant parts of the typedoc documentation within my code base and expose it directly in the documentation. This would allow the developers of my package to only need to care about the source code and typedoc. mkdocstrings-typescript would then take care of keeping in sync the documentation and the source code.

It would be useful to include only a subset of the entire package. We should be able to specify:

• Enumerations
  • Example: @package::Colors
  • Having the ability to specify a specific element of the enumeration would be useful instead of displaying all the elements.
  • Example: @package::Colors.RED
• Classes
  • Example: @package::Car
  • Having the ability to specify a specific method or property would also be really useful instead of having the full class properties and methods.
  • Example: @package::Car.startEngine or @package::Car.brand
• Interfaces
  • Example: @package::Vehicle
  • Having the ability to specify a specific method or property would also be really useful instead of having the full class.
  • Example: @package::Car.startEngine or @package::Car.brand
• Type Aliases
• Variables
  • Example: @package::NUMBER_OF_WHEELS_FOR_CARS
• Functions
  • Example: @package::getCars

Boost priority

• Boost priority in our backlog through Polar.sh. Higher pledge, higher priority.
• Minimum pledge by user/organization is $5, minimum amount for boost is $30.
• View all issues with pledges.
• We receive the funds once the issue is completed and confirmed by you.
• Features with the insiders label are released to sponsors first, and tied to a funding goal.

[pawamoy]

OK let's go with ::, we can always revise later!

[pawamoy]

@adaxi would you like to try out the obj-path branch (in the insiders repo)?

[adaxi]

Sure i'll try it out tomorrow!

[adaxi]

@pawamoy looks good, but it seems something else broke in the meanwhile.

When I include ::: @package::Whatever mkdocstrings-typescript seems to behave correctly.

But when I only include ::: @package I have the following error: (when I revert to the default theme, this does not occur).

ERROR   -  mkdocstrings: Template 'project.html.jinja' not found for 'typescript' handler and theme 'material'.
ERROR   -  Error reading page 'softphone.md': project.html.jinja
Traceback (most recent call last):
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
         ^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/mkdocs/__main__.py", line 288, in build_command
    build.build(cfg, dirty=not clean)
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/mkdocs/commands/build.py", line 310, in build
    _populate_page(file.page, config, files, dirty)
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/mkdocs/commands/build.py", line 167, in _populate_page
    page.render(config, files)
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/mkdocs/structure/pages.py", line 285, in render
    self.content = md.convert(self.markdown)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/markdown/core.py", line 357, in convert
    root = self.parser.parseDocument(self.lines).getroot()
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/markdown/blockparser.py", line 117, in parseDocument
    self.parseChunk(self.root, '\n'.join(lines))
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/markdown/blockparser.py", line 136, in parseChunk
    self.parseBlocks(parent, text.split('\n\n'))
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/markdown/blockparser.py", line 158, in parseBlocks
    if processor.run(parent, blocks) is not False:
       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/mkdocstrings/extension.py", line 130, in run
    html, handler, data = self._process_block(identifier, block, heading_level)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/mkdocstrings/extension.py", line 230, in _process_block
    rendered = handler.render(data, options)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/mkdocstrings_handlers/typescript/handler.py", line 187, in render
    return template.render(
           ^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/jinja2/environment.py", line 1304, in render
    self.environment.handle_exception()
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/jinja2/environment.py", line 939, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/mkdocstrings_handlers/typescript/templates/material/dispatch.html.jinja", line 1, in top-level template code
    {% extends "_base/dispatch.html.jinja" %}
    ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/mkdocstrings_handlers/typescript/templates/material/_base/dispatch.html.jinja", line 4, in top-level template code
    {% include "project.html.jinja" with context %}
^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/gbo/Workspaces/scp-sdk/docs/.venv/lib/python3.11/site-packages/jinja2/loaders.py", line 207, in get_source
    raise TemplateNotFound(template)
jinja2.exceptions.TemplateNotFound: project.html.jinja

Also, unrelated to this change, it seems that I am only getting the titles displayed in the generated output, the content is missing (no matter the theme being used)

[pawamoy]

Thanks! Let me fix try and fix these.

[adaxi]

@pawamoy any luck in reproducing the issue?

[pawamoy]

Thanks for the ping @adaxi. I've fixed the jinja2.exceptions.TemplateNotFound: project.html.jinja error in mkdocstrings-typescript 0.0.1.0.4.0 (which also includes the feature to specify an object path).

About the second issue, could you share one or two objects from your codebase (renaming and redacting any private stuff) that have "contents" (documentation comments I suppose?) so that I can investigate :slightly_smiling_face:?

Actually I think I have what I need in the repro repo. I'll give you an update in a few minutes.

[adaxi]

Yes, this example should reproduce it: https://github.com/mkdocstrings/griffe-typedoc-repro/blob/main/sdk/src/issues/i08.ts

I would expect to have the comment of the methods under the titles in the documentation

[pawamoy]

Yep! I looked into it, and the comments are not attached to the constructor or the function directly, but to their signatures. Working on a template.

[pawamoy]

I have pushed griffe-typedoc 0.0.0.0.2.13 and mkdocstrings-typescript 0.1.0.0.4.1, which should now show a few signatures and "docstrings". Work in progress.

[pawamoy]

I'll close this issue since the original topic is resolved I believe :slightly_smiling_face: