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.

Sign up for GitHub

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

Jump to bottom

[PROPOSAL] JuleDoc #126

Open
adamperkowski opened this issue Jan 13, 2025 · 3 comments
Open

[PROPOSAL] JuleDoc #126

adamperkowski opened this issue Jan 13, 2025 · 3 comments
Labels
proposal A proposal for new feature or changings

Comments

@adamperkowski
Copy link
Member

adamperkowski commented Jan 13, 2025 •
edited
Loading

Detailed description

We should make a tool that would be a simple documentation-from-source code generator, much like rustdoc (example) but far simpler.
It shouldn't be hard to write given what we already have.
JuleDoc preferably wouldn't have a webserver and output documentation in flexible formats:

  • HTML
  • Markdown
  • something that could be easily parsed and applied for a wide range of usecases

The output structure could look a little something like this (with highlight.js).

Context

I've attempted the miserable task of doing this manually with mdBook... This is just a pain:
https://snapbox.adamperkowski.dev/api.html
https://github.com/adamperkowski/snapbox/blob/main/book/src/api.md?plain=1#L1
@adamperkowski adamperkowski added the proposal A proposal for new feature or changings label Jan 13, 2025
@mertcandav mertcandav moved this to Active in proposals Jan 13, 2025
@mertcandav
Copy link
Member

mertcandav commented Jan 13, 2025 •
edited
Loading

Hi. This is already listed planned feature in the Future of Jule.
But this proposal will be a good point to start discuss about it.

There is no any standardization and beta version.
HTML and Markdown output formats seem feasible to me.

I think we have to declare a comment-line standard first before implementation.
Any suggestions appreciated.

@adamperkowski
Copy link
Member Author

I agree about the comments, forgot to mention that. I think we can also take inspiration from rust here:
https://doc.rust-lang.org/rust-by-example/meta/doc.html#doc-comments
https://doc.rust-lang.org/reference/comments.html

@mertcandav
Copy link
Member

Looks good, thanks.
I hope to provide more detailed feedback on this soon.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
proposal A proposal for new feature or changings
Projects
proposals
Status: Active
Milestone
No milestone
Development

No branches or pull requests
2 participants
@mertcandav @adamperkowski