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

fix: use absolute links for inherited items #105

Merged
merged 2 commits into from
May 11, 2024

Conversation

Nerixyz
Copy link
Contributor

@Nerixyz Nerixyz commented May 9, 2024

When compiling the documentation in this repository, you get a bunch of warnings about unknown links:

INFO    -  Doc file 'snippets/classes.md' contains a link '#typedef-parents', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-animal-13', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-animal-23', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-animal-33', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-get_name', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-get_num_of_eyes', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-get_num_of_limbs', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-get_parents', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-has_tail', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-operator-bool', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-some_inline_member_function', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-animal', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-find_child_by_name', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#function-find_parent_by_name', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#variable-father', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#variable-mother', but there is no such anchor on this page.
INFO    -  Doc file 'snippets/classes.md' contains a link '#variable-name', but there is no such anchor on this page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_block_quote.md' contains a link '#variable-children', but there is no such anchor on   
           this page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_block_quote.md' contains a link '#function-append', but there is no such anchor on this           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_block_quote.md' contains a link '#function-extend', but there is no such anchor on this           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_bold.md' contains a link '#variable-children', but there is no such anchor on this     
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_bold.md' contains a link '#function-append', but there is no such anchor on this page. 
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_bold.md' contains a link '#function-extend', but there is no such anchor on this page. 
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_header.md' contains a link '#variable-children', but there is no such anchor on this   
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_header.md' contains a link '#function-append', but there is no such anchor on this     
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_header.md' contains a link '#function-extend', but there is no such anchor on this     
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_hint.md' contains a link '#variable-children', but there is no such anchor on this     
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_hint.md' contains a link '#function-append', but there is no such anchor on this page. 
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_hint.md' contains a link '#function-extend', but there is no such anchor on this page. 
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_italic.md' contains a link '#variable-children', but there is no such anchor on this   
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_italic.md' contains a link '#function-append', but there is no such anchor on this     
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_italic.md' contains a link '#function-extend', but there is no such anchor on this     
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_link.md' contains a link '#variable-children', but there is no such anchor on this     
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_link.md' contains a link '#function-append', but there is no such anchor on this page. 
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_link.md' contains a link '#function-extend', but there is no such anchor on this page. 
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_list.md' contains a link '#variable-children', but there is no such anchor on this     
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_list.md' contains a link '#function-append', but there is no such anchor on this page. 
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_list.md' contains a link '#function-extend', but there is no such anchor on this page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_paragraph.md' contains a link '#variable-children', but there is no such anchor on this           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_paragraph.md' contains a link '#function-append', but there is no such anchor on this  
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_paragraph.md' contains a link '#function-extend', but there is no such anchor on this  
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_table.md' contains a link '#variable-children', but there is no such anchor on this    
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_table.md' contains a link '#function-append', but there is no such anchor on this page.INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_table.md' contains a link '#function-extend', but there is no such anchor on this page.INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_table_cell.md' contains a link '#variable-children', but there is no such anchor on    
           this page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_table_cell.md' contains a link '#function-append', but there is no such anchor on this 
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_table_cell.md' contains a link '#function-extend', but there is no such anchor on this 
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_table_row.md' contains a link '#variable-children', but there is no such anchor on this           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_table_row.md' contains a link '#function-append', but there is no such anchor on this  
           page.
INFO    -  Doc file 'mkdoxyApi/classmkdoxy_1_1markdown_1_1_md_table_row.md' contains a link '#function-extend', but there is no such anchor on this  
           page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#typedef-parents', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-animal-13', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-animal-23', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-animal-33', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-get_name', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-get_num_of_eyes', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-get_num_of_limbs', but there is no such anchor on this page.        
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-get_parents', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-has_tail', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-operator-bool', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-some_inline_member_function', but there is no such anchor on this   
           page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-animal', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-find_child_by_name', but there is no such anchor on this page.      
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#function-find_parent_by_name', but there is no such anchor on this page.     
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#variable-father', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#variable-mother', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_bird.md' contains a link '#variable-name', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#typedef-parents', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-bird-13', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-bird-23', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-bird-33', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-make_sound', but there is no such anchor on this page.      
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-move', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-bird', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-animal-13', but there is no such anchor on this page.       
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-animal-23', but there is no such anchor on this page.       
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-animal-33', but there is no such anchor on this page.       
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-get_name', but there is no such anchor on this page.        
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-get_num_of_eyes', but there is no such anchor on this page. 
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-get_num_of_limbs', but there is no such anchor on this page.INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-get_parents', but there is no such anchor on this page.     
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-has_tail', but there is no such anchor on this page.        
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-operator-bool', but there is no such anchor on this page.   
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-some_inline_member_function', but there is no such anchor on           this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-animal', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-find_child_by_name', but there is no such anchor on this    
           page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#function-find_parent_by_name', but there is no such anchor on this   
           page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#variable-father', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#variable-mother', but there is no such anchor on this page.
INFO    -  Doc file 'animal/classexample_1_1_special_bird.md' contains a link '#variable-name', but there is no such anchor on this page.

This PR fixes this by using absolute links when rendering inherited items or items embedded on other pages.


Btw, is there a way to see the generated markdown files? Or rather, where can I see them?

Copy link

@sourcery-ai sourcery-ai bot left a comment

Choose a reason for hiding this comment

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

We've reviewed this pull request using the Sourcery rules engine. If you would also like our AI-powered code review then let us know.

@JakubAndrysek
Copy link
Owner

Hi, it is a long known problem. Past versions of MkDocs did not support absolute links to files.
This support was added to the last version 1.6.0 - 3 weeks ago.

I found it, but I have not implemented it yet. A deeper look into the project and updating more generated files is needed.

If you want to look at it, add save-api: .mkdoxy into the yaml config. It will generate output into your configured folder.
image

I'll get to it in about a month at the earliest.
If you would like to fix snippet generation:

  • to working relative links
  • or use proper absolute links

I will be happy to accept your PR.

I have tested your PR, but for me, it returns the same Werning as previously.
But thank you for your job.
image

@Nerixyz
Copy link
Contributor Author

Nerixyz commented May 11, 2024

I have tested your PR, but for me, it returns the same Werning as previously.

These warnings are gone now. They were a bit unrelated as they're from the snippet generation. linkPrefix was only set for all nodes in the path from the target to the root node, but there could be other nodes outside the path referenced from a node inside it. One such case was the Type argument to the Animal constructor.


Since all generated files for one project are on a single level, it's fine to set the linkPrefix globally for a project.

@JakubAndrysek
Copy link
Owner

Thank you for your PR. I have tested it, and everything works well 😍

@JakubAndrysek JakubAndrysek merged commit ae20023 into JakubAndrysek:main May 11, 2024
13 checks passed
@Nerixyz Nerixyz deleted the fix/inherited-links branch May 11, 2024 15:06
@nihalshah-dev
Copy link

nihalshah-dev commented May 22, 2024

Hi, it is a long known problem. Past versions of MkDocs did not support absolute links to files. This support was added to the last version 1.6.0 - 3 weeks ago.

I found it, but I have not implemented it yet. A deeper look into the project and updating more generated files is needed.

If you want to look at it, add save-api: .mkdoxy into the yaml config. It will generate output into your configured folder. image

I'll get to it in about a month at the earliest. If you would like to fix snippet generation:

  • to working relative links
  • or use proper absolute links

I will be happy to accept your PR.

I have tested your PR, but for me, it returns the same Werning as previously. But thank you for your job. image

Hello @JakubAndrysek , Thanks for this wonderful plugin. I am trying to render output of mkdoxy through dev container. I want to store and see the output files in a custom folder, tried adding save-api function but somehow i am not able to see the folder.

My mkdoxy config looks like this -

image

image

DOXYFILE -->
image

Surprisingly, when i do mkdocs build.

  1. Output html files are stored in site/doxygen-demo
  2. Output markdown files are stored in site/assets/.doxy/doxygen-demo/doxygen-demo

FYI doxygen-demo == <NAME-OF-PROJECT>

Also If even after this works, is the addition of output files in nav section in mkdocs.yml a manual process?
image

will the following work in my case?

nav:
- 'Doxygen':
  - 'Doxygen-Demo': 'doxygen-demo/**'

Thanks!! Any ideas to resolve this?

Created an issue for this - #108

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants