search

JakubAndrysek / MkDoxy

📖 Automatically generates API documentation for your project based on Doxygen comments and code snippets in your markdown files.
https://mkdoxy.kubaandrysek.cz/
MIT License
60 stars 16 forks source link

fix: use absolute links for inherited items #105

Closed Nerixyz closed 1 month ago

Nerixyz commented 1 month ago

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?

JakubAndrysek commented 1 month ago

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:

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 commented 1 month ago

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 commented 1 month ago

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

nihalshah-dev commented 1 month ago

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 - https://github.com/JakubAndrysek/MkDoxy/issues/108