search

lem-project / lem

Common Lisp editor/IDE with high expansibility
http://lem-project.github.io/
MIT License
2.41k stars 182 forks source link

First step in creating a system to maintain documentation #644

Closed cxxxr closed 1 year ago

cxxxr commented 1 year ago

Context and scope

There is currently an issue with not having well-maintained user guides and developer documentation. As a first step, I tried to consolidate commands and key bindings in d145f76c07aba62df0f2d69adcd0684bbee12627. However, preparing and maintaining these for all functionalities is challenging, as it lacks maintainability and scalability.

One possible solution is to generate documentation using command definitions, key bindings, and docstrings, and present that documentation on Lem with clickable links.

Goals

The initial goal is to enable automatic generation of documentation similar to d145f76c07aba62df0f2d69adcd0684bbee12627.

Non goals

Complete documentation

Only easy problems will be tackled at first.

Rich markdown viewer

This is done by another issue

Multilingual support

Currently, only English will be provided

ToDo

First, the commands will be divided into packages based on their genres. This will allow writing descriptions about each command in the package's docstring.

The following files are likely to be targeted:

After that, I will extract information from the runtime and generate Markdown files. These Markdown files will be placed in the docs/ directory. (The directory may be changed to a more appropriate location later.)

Sasanidas commented 1 year ago

One possible solution is to generate documentation using command definitions, key bindings, and docstrings, and present that documentation on Lem with clickable links.

Maybe something similar to https://github.com/Wilfred/helpful , maybe extending the typeout mode (or having a major-mode in that buffer) to reflect the syntax and having the buttons.

cxxxr commented 1 year ago

This may be helpful. Thank you for letting me know.

Sasanidas commented 1 year ago

I took the liberty to try and make a webpage for more user friendly documentation, for now is in https://sasanidas.github.io/lem-page/

If you (@cxxxr) think that can be suitable for the project, I am more than happy to move it to the lem project workspace (also ping @vindarel that I saw making some documentation)

(I just realize that this also solve the issue https://github.com/lem-project/lem/issues/86)

cxxxr commented 1 year ago

This is really wonderful! If this document is included in the lem-project, I would be very grateful and will continue to maintain it. And, if it's not too much to ask, would you consider becoming a collaborator as well? (@Sasanidas @vindarel)

Sasanidas commented 1 year ago

And, if it's not too much to ask, would you consider becoming a collaborator as well?

Sure! I'll be more than happy to help :raised_hands: , if you add me to the organization, I'll transfer the lem-page repository

cxxxr commented 1 year ago

Thank you. I sent you an invitation.

Sasanidas commented 1 year ago

Nice, thanks, I moved the repository (https://github.com/lem-project/lem-page) and now the webpage is up! (https://lem-project.github.io/lem-page/)

Can I have development access to the repository? I still wanna change some things

cxxxr commented 1 year ago

Thank you for the moved the repository.

Can I have development access to the repository? I still wanna change some things

I invited you to the organization, so I believe they probably have the necessary authority.

Sasanidas commented 1 year ago

I invited you to the organization, so I believe they probably have the necessary authority.

Umm... I was going to change the about of the lem-page repository but I can't, maybe there are other permissions per repository?

cxxxr commented 1 year ago

Sorry, I've changed the permission settings in the repository, because it seems I didn't set them enough. How about now?

Sasanidas commented 1 year ago

Oh, now I can, thanks! :+1:

Sasanidas commented 1 year ago

I think the page is ready to make it visible in the README and/or in the description in the lem project :+1:

cxxxr commented 1 year ago

I'm very happy and grateful :pray: I have also reflected it in the repository description.

vindarel commented 1 year ago

Well done!!

So it's using Hugo with https://github.com/thegeeklab/hugo-geekdoc -I like it.

would you consider becoming a collaborator as well? (@vindarel)

sure, please allow me to write more documentation! : )

I think there is both the need of an automatic, extensive documentation generator (for internals, etc)

and a manual for end-users -this new page.

cxxxr commented 1 year ago

Yes, I agree with the idea that only some can be generated automatically and most need to be maintained by hand.

cxxxr commented 1 year ago

I think it completed.

jcs090218 commented 1 year ago

Some thoughts on the documentation page.

I'm seeing translation from Japanese to English, but hugo supports multilingual. Wouldn't it be better if we host multiple languages instead of translation? 🤔 Of course, it will be harder for maintainers to maintain, but it's a nice thing to have.

For example, I've created a manual for my project Eask at https://emacs-eask.github.io/. And it supports English and Traditional Chinese, two languages.

Sasanidas commented 1 year ago

I'm seeing translation from Japanese to English, but hugo supports multilingual. Wouldn't it be better if we host multiple languages instead of translation? thinking Of course, it will be harder for maintainers to maintain, but it's a nice thing to have.

Ummm, I think it can be interesting in the long run, and it's quite easy to modify the code base to adapt to it, but as you mention, having to maintain multiple languages is complicated with a small community. But given that the creator is from Japan and there is probably a good amount of user there, maybe it's more desirable to have both version (japanese and english for example)

jcs090218 commented 1 year ago

I brought up this because there are many common-lisp users in China, so I plan to help with the Chinese version. This should make this project gains more popularity in the Mandarin market. WDYT? 🤔

Sasanidas commented 1 year ago

I brought up this because there are many common-lisp users in China, so I plan to help with the Chinese version. This should make this project gains more popularity in the Mandarin market. WDYT? thinking

Oh! It sounds great, well, if that's the case, I guess that's a compelling reason if @cxxxr wants, I'll add the multilanguage :+1:

cxxxr commented 1 year ago

I agree with the multilingual support! I thought English was the only language in demand, but I guess my perception was a little off.

jcs090218 commented 1 year ago

@cxxxr Do you mind if I can join the org? I want to contribute and follow this project actively, so it helps me link the project under my GitHub profile page!

I am probably not able to go too deep to the core yet since I'm still reading the source code. But so far so good; I really like the project! 🚀 Will like to send more patches regarding documentation etc.

I agree with the multilingual support!

Source code should be in English for sure, but we have more control for the site! 😉

I thought English was the only language in demand, but I guess my perception was a little off.

Yeah, it's a waste since you already have it under Japanese! Then I can translate either Japanese/English to Traditional/Simplified Chinese! Can't wait to show this project to the Mandarin world! 😊

cxxxr commented 1 year ago

@jcs090218

Do you mind if I can join the org?

Yes, please join us! I am so very glad you are interested in lem, thank you so much.

jcs090218 commented 1 year ago

Thank you so much! :D

I am so very glad you are interested in lem, thank you so much.

It's a wonder project! ;)