Implement multiple pages cross-reference for MkdocsRenderer

thedemons commented 2 years ago

I have implemented the multiple pages cross-reference resolver. Here are the details.

Preview:

What changed:

Added SmartReferenceResolver in the module contrib/renderer/smartresolver.py
MkdocsRenderer is now using the new resolver to solve cross-reference across multiple pages.

Features of the new resolver:

Find the reference in:
- The current module, works just like the old one with a little bit of enhancement.
- All of the imported modules, it is able to solve from x import *.
- All of the project files, you could just reference it from anywhere without having to import the actual reference.

New options for MkdocsRenderer:

crossref_local:
- Find the reference in the current module.
- Works like the default resolver but with a little bit of enhancement.
- Default to True.
crossref_import:
- Find the reference in all of the imported modules.
- The resolver will look for any references in all of the imported modules.
- This option requires you to give it the exact name of the reference
- For example, if you import typing to use typing.List, then referencing #typing.List is valid, but #List is not.
- This also works for from typing import *
- Default to True.
crossref_global:
- Find the reference in all of the project files.
- The resolver will take a look at all modules of the project and fine the reference.
- It will return the closest, top-matched reference.
- The crossref_import option requires you to give it the exact module and name of the reference.
- But this is not, you only need to give it the name of the reference.
- Default to False.

Known issue:

RecursionError: the crossref_import option for some reason keeps recursively looking for built-in modules (like typing or os) in between two modules. This had been solved by checking if the previous searched module is equal to the next module in the queue.

Example .yml for setting up the crossref options:

renderer:
  type: mkdocs
  crossref_local: true
  crossref_import: true
  crossref_global: true

Live preview:

You can see the live preview here, which was built using pydoc-markdown plus some of my customizations.

NiklasRosenstein commented 2 years ago

Hey @thedemons ! This is awesome, thanks a lot for your work! Just want to let you know that I might need a few days to examine the PR.

thedemons commented 2 years ago

Hey @thedemons ! This is awesome, thanks a lot for your work! Just want to let you know that I might need a few days to examine the PR.

Thanks. I didn't know how to implement it properly so you might want to edit the code a little bit.

Please take a look at the method get_resolver() in MkdocsRenderer. It will now return SmartReferenceResolver object instead of calling MarkdownRenderer.get_resolver() because the new resolver need to have a reference to the MkdocsRenderer object in order to find the page url in MkdocsRenderer.pages I was thinking of changing the code in the base Renderer class itself but i think that's too much changes for the code base.

The new resolver might also works for HugoRenderer but i haven't tested it yet.

thedemons commented 2 years ago

Hi @NiklasRosenstein, any updates?

thedemons commented 2 years ago

Hey @thedemons ,

Sorry for the delay here. I've left a few notes, I'm done skimming the code but I'll go in some more depth later today.

Thanks for the review, I realized that my code is ugly, mostly because this was orginaly created for my personal project only.

I will resolve those issues asap.

NiklasRosenstein commented 2 years ago

Just want to give you a heads-up that linking across pages is now natively supported when using Novella as the build backend in Pydoc-Markdown 4.6.0 (currently on develop and not yet released). You can check out the documentation to find more details about Novella here: http://niklasrosenstein.github.io/pydoc-markdown/

The Renderer plugins from Pydoc-Markdown will be supported for a while longer, but my focus will be shifting towards improving the integration with Novella. I'm still happy to merge this for anyway who is currently using the Pydoc-Markdown MkDocs integration, but in the next major version (which may be a while to go) that will go away.

Cheers,

thedemons commented 2 years ago

Just want to give you a heads-up that linking across pages is now natively supported when using Novella as the build backend in Pydoc-Markdown 4.6.0 (currently on develop and not yet released). You can check out the documentation to find more details about Novella here: http://niklasrosenstein.github.io/pydoc-markdown/

The Renderer plugins from Pydoc-Markdown will be supported for a while longer, but my focus will be shifting towards improving the integration with Novella. I'm still happy to merge this for anyway who is currently using the Pydoc-Markdown MkDocs integration, but in the next major version (which may be a while to go) that will go away.

Cheers,

That's awesome, sorry that I'm too busy right now to work on this PR, I'll close this and maybe will continue work on it on my 4.5 fork.

Thanks for reviewing my code tho

NiklasRosenstein / pydoc-markdown