Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve API documentation #16140

Merged
merged 12 commits into from
Apr 12, 2024
Merged

Improve API documentation #16140

merged 12 commits into from
Apr 12, 2024

Conversation

fcollonval
Copy link
Member

@fcollonval fcollonval commented Apr 9, 2024 •
edited

References

Typedoc configuration changes are required for #15916. This extracts the improvements in a dedicated PR.

Code changes

  • Change the configuration of typedoc to use the entryPointStrategy: 'packages' as recommended for monorepo.
  • The consequence is the generation of links to GitHub source (see screenshots below).
  • Remove dead config for typedoc (in particular reference to dedicated theme)
  • Fix some doc warnings (hence changes in code source)

User-facing changes

Before After
image image

Backwards-incompatible changes

None

@jupyterlab-probot jupyterlab-probot
Copy link

Thanks for making a pull request to jupyterlab!
To try out this branch on binder, follow this link: Binder

@fcollonval fcollonval added this to the 4.2.0 milestone Apr 10, 2024
@fcollonval fcollonval marked this pull request as ready for review April 10, 2024 07:35
@krassowski
Copy link
Member

  • Change the configuration of typedoc to use the entryPointStrategy: 'packages' as recommended for monorepo.
  • The consequence is the generation of links to GitHub source (see screenshots below).

It looks that already without the monorepo setup we were getting links for some - but not other - code locations. Why is that? For example

image

From the other changes it looks like the monorepo setup is a bit of an overkill as it groups packages by namespace and we have only one namespace:

image

which frankly I would expect to be the case for many monorepos.

@jtpio
Copy link
Member

jtpio commented Apr 11, 2024 •
edited

Remove dead config for typedoc (in particular reference to dedicated theme)

So does this fix / close #11788?

@fcollonval
Copy link
Member Author

Remove dead config for typedoc (in particular reference to dedicated theme)

So does this fix / close #11788?

In fact we should close that issue because the feature excludeNotExported has been removed in typedoc for a while. So we won't be able to restore the feature behind the need for a custom theme.

Xref: TypeStrong/typedoc@2058981

@fcollonval
Copy link
Member Author

fcollonval commented Apr 11, 2024 •
edited

  • Change the configuration of typedoc to use the entryPointStrategy: 'packages' as recommended for monorepo.
  • The consequence is the generation of links to GitHub source (see screenshots below).

It looks that already without the monorepo setup we were getting links for some - but not other - code locations. Why is that?

Good question, I actually missed that some links are working. But my guess is that it will be though without the mono repo approach as typedoc is trying to build the all monorepo at once; hence I guess a mixture of typing files and source files.

From the other changes it looks like the monorepo setup is a bit of an overkill as it groups packages by namespace and we have only one namespace:

which frankly I would expect to be the case for many monorepos.

I agree I don't like it either. I'll give an another trial to be closer to the current behavior.

@jtpio jtpio mentioned this pull request Apr 11, 2024
Closed
@krassowski krassowski self-requested a review April 11, 2024 21:06
@fcollonval
Copy link
Member Author

I updated the screenshot in the first comment; it is very similar. It is possible to drop the version. But I think it is an interesting information to display in particular as we will slowly have more specific package version increments,

@fcollonval fcollonval mentioned this pull request Apr 12, 2024
Merged
krassowski
krassowski reviewed Apr 12, 2024
View reviewed changes
Copy link
Member

@krassowski krassowski left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great! The version numbers are a bit distracting, but maybe I will get used to them.

package.json Outdated Show resolved Hide resolved
packages/application/src/shell.ts Show resolved Hide resolved
packages/completer/src/reconciliator.ts
@@ -17,7 +17,8 @@ import { Completer } from './widget';
import { Signal } from '@lumino/signaling';

// Shorthand for readability.
type InlineResult = IInlineCompletionList<CompletionHandler.IInlineItem> | null;
export type InlineResult =
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if we need to export this, it is just a shorthand.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typedoc is complaining because it does not resolve shorthand...

fcollonval and others added 2 commits April 12, 2024 10:40
@fcollonval @krassowski
Apply suggestions from code review
bf532c1 
Co-authored-by: Michał Krassowski <5832902+krassowski@users.noreply.github.com>
@fcollonval
Keep the old ITopArea
cc9c7ab
@krassowski
Copy link
Member

yarn.lock needs updating

krassowski
krassowski approved these changes Apr 12, 2024
View reviewed changes
Copy link
Member

@krassowski krassowski left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @fcollonval!

@krassowski krassowski merged commit f7e5022 into jupyterlab:main Apr 12, 2024
81 of 82 checks passed
gderocher pushed a commit to gderocher/jupyterlab that referenced this pull request Apr 26, 2024
@fcollonval @pre-commit-ci
@krassowski @gderocher
Improve API documentation (jupyterlab#16140)
570e855 
* Update typedoc config

* Clean up typedoc dead code

* Prettify

* Remove some typedoc warnings

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Prettify

* Change naming hierarchy to reduce changes

* Minor JS doc improvements

* Prettify

* Apply suggestions from code review

Co-authored-by: Michał Krassowski <5832902+krassowski@users.noreply.github.com>

* Keep the old `ITopArea`

* Fix yarn.lock

---------

Co-authored-by: Frédéric Collonval <fcollonval@users.noreply.github.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Michał Krassowski <5832902+krassowski@users.noreply.github.com>
@fcollonval fcollonval deleted the enh/improve-api-doc branch April 29, 2024 14:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@krassowski krassowski krassowski approved these changes

Assignees

@fcollonval fcollonval

Labels
documentation pkg:application pkg:apputils pkg:attachments pkg:cell-toolbar pkg:cells pkg:celltags pkg:codeeditor pkg:codemirror pkg:completer pkg:console pkg:coreutils pkg:csvviewer pkg:debugger pkg:docmanager pkg:docregistry pkg:documentsearch pkg:extensionmanager pkg:filebrowser pkg:fileeditor pkg:help pkg:htmlviewer pkg:hub pkg:imageviewer pkg:inspector pkg:javascript pkg:json pkg:launcher pkg:logconsole pkg:lsp pkg:mainmenu pkg:markdownviewer pkg:mathjax pkg:mermaid pkg:metadataform pkg:notebook pkg:observables pkg:outputarea pkg:pdf pkg:pluginmanager pkg:property-inspector pkg:rendermime pkg:running pkg:services pkg:settingeditor pkg:settingregistry pkg:shortcuts pkg:statedb pkg:statusbar pkg:terminal pkg:themes pkg:toc pkg:tooltip pkg:translation pkg:ui-components pkg:vega pkg:workspaces tag:Testing
Projects
None yet
Milestone
4.2.0
Development

Successfully merging this pull request may close these issues.

None yet
3 participants
@fcollonval @krassowski @jtpio