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.

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

docs: fix links in code snippets #6734

Merged

Conversation

jakovljevic-mladen
Copy link
Member

Description:
I'm once again sorry for the very large PR. This PR fixes issue where autoLinkCode wasn't able to produce links in code snippets. For example, if there was a snippet like this (in any exported .ts or .md file):

import { from, Subject } from 'rxjs';
import { multicast } from 'rxjs/operators';
 
const source = from([1, 2, 3]);
const subject = new Subject();
const multicasted = source.pipe(multicast(subject));
 
// These are, under the hood, `subject.subscribe({...})`:
multicasted.subscribe({
  next: (v) => console.log(`observerA: ${v}`)
});
multicasted.subscribe({
  next: (v) => console.log(`observerB: ${v}`)
});
 
// This is, under the hood, `source.subscribe(subject)`:
multicasted.connect();

autoLinkCode would generate links wherever from, Subject and multicast were written because from, Subject and multicast are valid documentation pages.

The real reason why this autoLinkCode failed to do some processing was that it was actually excluded from postProcessHtml.plugins. At first, it was added to the postProcessHtml.plugins array, but later, plugins array was overwritten with another array (with a embedMarbleDiagramsPostProcessor plugin). Now, I fixed it to push embedMarbleDiagramsPostProcessor to an existing array instead of creating a new one.

autoLinkCode was adjusted so that it follows the same code structure from Angular project.

Also, one more thing that embedMarbleDiagramsPostProcessor was doing is that it was copying files from docs_app/src/assets/images/marble-diagrams/ to docs_app/assets/ for no particular reason. I couldn't ever find where these files have been used, because all images in the app have had src tag that included assets/images/marble-diagrams/ path. For that reason, I removed copying these files, I removed all copied files and I removed the dependency associated with that - mkdirp.

With removal of mkdirp, I noticed another package that was accidentally added that's never used - typedoc. The docs generation is done by Angular scripts.

Since these old (and reintroduced) postProcessHtml.plugins were never used for more than 2 years, some docs are now having multiple issues. One of the issues is that there are multiple docs where there are multiple H1 HTML tags. For that reason, I disabled a processor that checks that because it fails to generate scripts. I will try to fix those issues if this PR lands to master.

One last note: while I was creating PRs related to #6627, I forgot to remove old images (audit.png, debounce.png and throttle.png), so I removed them here.

Related issue (if exists):
None, only this comment.

@jakovljevic-mladen
Copy link
Member Author

This is how changes from this PR look like:

RxJS - code examples have links again

(Please notice the commit hash in the end of gif, it matches the one from this PR.)

Copy link
Member

@benlesh benlesh left a comment

Choose a reason for hiding this comment

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

This looks great, thank you.

@benlesh benlesh added 7.x Issues and PRs for version 6.x 8.x Issues and PRs for version 8.x labels Jan 4, 2022
@benlesh benlesh merged commit 7268bd3 into ReactiveX:master Jan 4, 2022
@benlesh benlesh mentioned this pull request Jan 4, 2022
@jakovljevic-mladen jakovljevic-mladen deleted the fix_links_in_code_snippets branch January 4, 2022 18:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
7.x Issues and PRs for version 6.x 8.x Issues and PRs for version 8.x
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants