search

SquidDev / illuaminate

Very WIP static analysis for Lua
https://squiddev.cc/illuaminate/
BSD 3-Clause "New" or "Revised" License
49 stars 2 forks source link

Function/list/method source override annotation tag #46

Closed 9551-Dev closed 1 year ago

9551-Dev commented 1 year ago

Hey, sorry if this is the wrong place to ask but would it be possible to add a tag like --@source which would allow me to change where the source buttons links to?

This would be useful because i format my things in such way (and my api is designed in such way) that makes it really hard to define the annotations within the source code. So what i do is i have a part of the internal api be used for assigning docs to each registry entry (i use registries to store all the data of my api) and then i have that generate an illuaminate project including the sexp file.

However this does not contain the actual source code and its just a lua file with empty function definitions

It would be really useful if i could generate a link to the actual source code (in the github repo) with my api and then just put it in the illuaminate project and have illuaminate source button actually point to the link in the actual source (which i would generate)

If this would not be possible to implement could you atleast please give me some guidance on where to look so i can fork illuaminate and add such a feature myself for my own usecase

SquidDev commented 1 year ago

Yep! This should be supported already, as we need to do something similar for cct-javadoc.

It takes the form @source <path>:<line>, so for example something like:

@source projects/common/src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java:24

Let me know if that is/isn't enough for your use-case!

9551-Dev commented 1 year ago

Yep! This should be supported already, as we need to do something similar for cct-javadoc.

It takes the form @source <path>:<line>, so for example something like:

@source projects/common/src/main/java/dan200/computercraft/shared/peripheral/commandblock/CommandBlockPeripheral.java:24

Let me know if that is/isn't enough for your use-case!

Lovely! Thanks will give it a try as soon as i can but it looks like it should do! However can i have it use a different link instead of just switching the path? As i have the docs be generated in a different repository than the source is in.

It would be nice if i could set it to any path.

SquidDev commented 1 year ago

[...] and then i have that generate an illuaminate project including the sexp file.

Just to confirm, are you doing this manually or automatically? I couldn't see anything obvious in the C3D or C3D-Docs repos.

9551-Dev commented 1 year ago

[...] and then i have that generate an illuaminate project including the sexp file.

Just to confirm, are you doing this manually or automatically? I couldn't see anything obvious in the C3D or C3D-Docs repos.

Sorry for the confusion, how my thing works is that in each file you define the docs with code and the use special annotation on the function to link it to that doc data

That generates the illuminate type lua files and the sexp file That is being done fully automaticall

While the C3D repo contains the source (and will aldo contain the docs definitions with my own custom system. Note that this isnt in the public repo yet so you wont see it!)

The C3D-docs will store just the illuminate files with empty annotated functions and no actual source code.

From what I understand this source annotation needs the source to be somewhere accessible withing the same page/repo for it to link correctly but that's not the case as the actual source code is in a separate repo split from the generate doc lua files

SquidDev commented 1 year ago

The C3D-docs will store just the illuminate files with empty annotated functions and no actual source code.

What's the motivation for a separate repo here? It feels like it might be easier just to generate these intermediate files in CI, and then publish the final HTML to GitHub pages directly.

SquidDev commented 1 year ago

Also, at the risk of undermining my own project here, I'm not entirely sure if it's actually worth you using illuaminate here. IMO the main value add is the automatic extraction of comments from source code - you've solved that a different way, so I kinda wonder if you're better off just spitting out markdown and then that feeding that into mkdocs or something.

9551-Dev commented 1 year ago

Also, at the risk of undermining my own project here, I'm not entirely sure if it's actually worth you using illuaminate here. IMO the main value add is the automatic extraction of comments from source code - you've solved that a different way, so I kinda wonder if you're better off just spitting out markdown and then that feeding that into mkdocs or something.

Im still trying to get illuminate working as i really like it's features and looks, plus ive done dome theming for it

9551-Dev commented 1 year ago

The C3D-docs will store just the illuminate files with empty annotated functions and no actual source code.

What's the motivation for a separate repo here? It feels like it might be easier just to generate these intermediate files in CI, and then publish the final HTML to GitHub pages directly.

I could do that! Thanks that would probably resolve the issue.

If there are any issues i will be back but tbh i donz even remember why i made it a separate repo