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



Copy link

@jakovljevic-mladen jakovljevic-mladen commented Dec 28, 2021

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({...})`:
  next: (v) => console.log(`observerA: ${v}`)
  next: (v) => console.log(`observerB: ${v}`)
// This is, under the hood, `source.subscribe(subject)`:

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.

Copy link
Member Author

@jakovljevic-mladen jakovljevic-mladen commented Dec 28, 2021

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.)

benlesh approved these changes Jan 4, 2022
Copy link

@benlesh benlesh left a comment

This looks great, thank you.

@benlesh benlesh added 7.x 8.x labels Jan 4, 2022
@benlesh benlesh merged commit 7268bd3 into ReactiveX:master Jan 4, 2022
5 checks passed
@benlesh benlesh mentioned this pull request Jan 4, 2022
@jakovljevic-mladen jakovljevic-mladen deleted the fix_links_in_code_snippets branch Jan 4, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
7.x 8.x
None yet

Successfully merging this pull request may close these issues.

None yet

2 participants