Comments (18)
One frustration I have with typedoc is that it doesn't seem to support crosslinks between the packages, at least with our current setup. I would love for the docs of one module that referenced interfaces defined in another module to link to that other module's documentation, for example.
Is there a way to get typedoc to document multiple modules at once to provide this crosslinking? I investigated this for a bit last week, but didn't find a way forward.
from lumino.
I was considering Lumino to handle window management in a React application. Inspired by @kinow 's work but with a slightly different approach I was able to draw widgets that are able to access the Redux application state and to add widgets using Redux actions.
For anyone interested in using @lumino/widgets
inside a React application: the proof of concept is available here. Thanks for continuing phosphorjs and making this available to us!
from lumino.
Very nice, thanks for sharing @ccssmnn!
from lumino.
I can put in some cycles here, but don't want to carry it myself. Who else? :)
from lumino.
I did some experimentation today with sphinx_js
.
Here are the issues I faced:
- We have to manually create all of the entries for classes, functions, etc.
- Because of the monorepo, we would need a top level package.json and tsconfig.json that worked for all of the packages. Example output:
Running Sphinx v2.2.1
Using TypeScript 3.7.2 from /Users/steve/miniconda/lib/node_modules/typedoc/node_modules/typescript/lib
Error: Cannot find global value 'Promise'.
Error: /Users/steve/workspace/jupyter/lumino/packages/algorithm/src/array.ts(15)
Cannot use imports, exports, or module augmentations when '--module' is 'none'.
Error: /Users/steve/workspace/jupyter/lumino/packages/algorithm/src/sort.ts(43)
Cannot find name 'Set'. Do you need to change your target library? Try changing the `lib` compiler option to es2015 or later.
Error: /Users/steve/workspace/jupyter/lumino/packages/algorithm/src/sort.ts(44)
Error: /Users/steve/workspace/jupyter/lumino/packages/algorithm/src/sort.ts(44)
Cannot find name 'Map'. Do you need to change your target library? Try changing the `lib` compiler option to es2015 or later.
Error: /Users/steve/workspace/jupyter/lumino/packages/algorithm/tests/src/array.spec.ts(11)
Cannot find module 'chai'.
I also tried making a self-contained sphinx doc build in one of the packages, but ran into similar issues.
My inclination is that we stick with Typedoc and come up with a workflow (potentially using GitHub actions) that updates a jupyterlab.github.io repo with both lumino docs and JupyterLab docs. I'll bring this up for discussion at the dev meeting on Wednesday.
from lumino.
Api-extractor might solve some or all of these issues?
from lumino.
Thanks @vidartf, I think that is correct. api-extractor can take a folder that contains separately created api.json
files and create a cohesive set of .md
files, which we can then reference from sphinx.
https://api-extractor.com/pages/setup/generating_docs/
from lumino.
Some open questions though:
- Will the default markdown render suffice (API docs have internal inter-linking, but no RST refs from outside into it)?
- Can we write some plugin for the markdown renderer to add some recommonmark magic to allow refs to entries from the RST code?
- Should we create an RST documentation writer?
I'm proposing we start with the former, and simple RST links. Then we consider https://api-extractor.com/pages/setup/custom_docs/ as needed.
from lumino.
I agree it is enough to start with internal inter-linking.
from lumino.
Never used Phosphor, or lumino. But we are evaluating it for our app. So I'll be watching this issue/repo and can help reviewing docs, testing examples, and trying to suggest one thing or two
from lumino.
Some parts definitely worth considering:
- Project overview/intro page
- Getting started guides (one for widgets, one for application?): How to get a simple example webpage using widgets / an application with plugins up and running ("boiler-plate guide").
- High-level overview of widgets package concepts.
- Major components (widgets, panels, layouts, and the split in responsibilities between them).
- What is the role of widgets, what is it not: Not a full controls library (compared to e.g. Qt that does both windows/frames/app/etc. but also comboboxes, checkboxes etc.).
- How does widgets get added to the DOM?
- Tie in secondary concepts such as signals, messages, disposables etc, linking to more in-depth docs for those.
- What are the steps involved in an initial layout or a layout update? (messages, how messages propagate in the DOM tree, who is responsible for the propagation, and what are ways to modify/interfere with it)?
- Which bits of the logic do a user need to care about if creating a "leaf" widget, vs if they want to create a new panel (i.e. layout widget).
- High-level overview of application package concepts.
- What problem is it meant to solve?
- Why does it do it the way it does?
- Which questions are left open for the application implementer to resolve (e.g. how to get/manage a collection of plugins)?
- Write a "package documentation" for each package. This can maybe be done with a docstring in index.ts files:
Alternatively, it might be written directly as markdown files.
/** * @packageDocumentation * Lorem ipsum... */
from lumino.
I had looked at two solutions still in the typedoc camp for another project...
However, if
api-generator
looks like like the way to go, and has output based on a schema, I've no complaints!
- https://github.com/marcj/typedoc-plugin-lerna-packages
- the top-level links include the namespace, e.g.
@lumino/algorithm
- the top-level links include the namespace, e.g.
- https://github.com/unstubbable/typedoc-plugin-monorepo
- top level links are "cleaned", e.g.
algorithm
- top level links are "cleaned", e.g.
...both of them will do a single-cli-invocation generation of the same structure as the current API, but with an overarching index.html
. However, per @jasongrout's gripe, neither of them will link up things like Widget implements IObservableDisposable
, even though they're all in scope during the build, which is indeed frustrating. I'm not sure how much deeper into the pipe it's worth going.
I had some earlier success with getting the output of the lerna-based one to work with sphinx_js
on another project, but it's quite sensitive to the output of jsdoc/typedoc's JSON output, which both seem to change fairly casually between minor versions, which is hard to stay on top of.
from lumino.
Had a look at the output of api-documentor
: it looks like eponymous class/namespace pairs get clobbered, such that widgets.widget.md only contains the namespace contents and not the class information, while things like the Widget constructor expect to be linking to the class. Haven't looked into what it would take to untangle them...
from lumino.
Blunt-force adding the kind
to the the filename in MarkdownDocumenter.ts
did the trick:
private _getFilenameForApiItem(apiItem: ApiItem): string {
...
return baseName + "." + apiItem.kind.toLowerCase() + ".md";
}
(this yields widgets.widget.class.md
and widgets.widget.namespace.md
, and back-links work as expected)
It's also possible (though required bringing in a fair amount of machinery from YamlDocumenter
) to get links in next to signatures:
private _writeApiItemPage(apiItem: ApiItem): void {
...
output.appendNode(
new DocFencedCode({
configuration,
code: apiItem.getExcerptWithModifiers(),
language: "typescript"
})
);
const signatureLinks: DocLinkTag[] = [];
for (const token of apiItem.excerptTokens) {
if (token.kind == ExcerptTokenKind.Reference) {
const specUid: string | undefined =
token.canonicalReference && token.canonicalReference.toString();
if (specUid != null) {
const linkedItem = this._apiItemsByCanonicalReference.get( // copied this from yaml
specUid
);
if (linkedItem != null) {
signatureLinks.push(
new DocLinkTag({
configuration,
tagName: "@link",
linkText: token.text,
urlDestination: this._getLinkFilenameForApiItem(linkedItem)
})
);
}
}
}
}
if (signatureLinks.length) {
output.appendNode(
new DocParagraph({ configuration }, signatureLinks)
);
}
...
Yielding:
#```typescript
export declare class Widget implements IMessageHandler, IObservableDisposable
#```
[IMessageHandler](./messaging.imessagehandler.interface.md)[IObservableDisposable](./disposable.iobservabledisposable.interface.md)
It would take some doing (if even possible in markdown) to get syntax-highlighted, linked signatures.
On the whole, it's a pretty impressive piece of work, and it seems like a light fork (or set of PRs) would provide the features we're seeking. An RstDocumenter.ts
would certainly create a lot of benefit, specifically for labextensions, but would also be a large amount of work, especially if things needed to exist that weren't already covered by tsdoc
.
from lumino.
We are using Vue.js with Lumino, which brings some challenges as Vue.js components work with the Virtual-DOM, but Lumino widgets interact directly with the DOM. We got an example that can be used by other Vue.js devs as reference for one way to integrate Vue.js and Lumino: https://github.com/kinow/vue-lumino
Let me know in case there's any place in the documentation with links for integrations like this
Thanks
Bruno
from lumino.
Hi @kinow, nice work! I think for now it would be appropriate to add an External Examples
section to the README and start with a pointer to your repository.
from lumino.
Thanks @blink1073 ! Done: #59
from lumino.
Hi! I ran into some doc improvement opportunities when building my first extension.
The main one is that itโs unclear what you can specify your extension requires
: It seems clear from context that itโs an interface, but not which interface have one global object that you can retrieve that way.
I assume everything that is a Token
can be used that way (?) but TypeDoc doesnโt integrate here: Token
is only available on https://jupyterlab.github.io/lumino/coreutils and not on https://jupyterlab.github.io/jupyterlab/modules where it would be useful.
Ideally, the narrative docs should link to an automatic list of all tokens that jupyterlab/modules provides (or, if not all tokens are able to occur in requires
, a list of all that do)
from lumino.
Related Issues (20)
- Preview tab HOT 6
- Widgets should not add/remove `aria-hidden` in `display` (and maybe `contentVisibility`) hidden mode HOT 1
- Containers with managed size and position should use `contain:strict`
- Resizing of panels is slow when there are many nodes in resized notebooks/widgets HOT 1
- Focus new tab every time current tab is changed HOT 2
- Lumino should not set cursor (css issue) HOT 2
- [DataGrid] Add ability to resize a column's width to fit its content HOT 2
- Add classList to Widget.title to streamline class manipulation
- macOS: Emoji used for "enter" in pulldown menu keyboard shortcuts HOT 1
- Duplicate HOT 2
- Duplicate
- [DataGrid] double-clicking cells to edit them is flakey HOT 11
- The `Title.changed` signal could emit some detail about the change
- Should commands receive an event that triggered them? HOT 2
- Deprecation in 1.x without fix HOT 2
- Allow a custom label for menu items, overriding the command name HOT 2
- Dock panels with reusable splits HOT 2
- Reuse the plugin system without depending on the Lumino Widgets HOT 3
- Drag image is rendered off-screen HOT 3
- MenuBar example is currently broken HOT 5
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. ๐๐๐
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google โค๏ธ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from lumino.