Who maintains this project?
hiperiondev opened this issue · 37 comments
From what I see there is not much movement in the source.
I also did the translation of the documentation to spanish and there was no response on that.
On the other hand, the original documentation is outdated.
@skiars is the owner of the project. I'm doing mostly fixes and extensions.
There has been some significant effort on the wiki documentation. What part of the documentation is outdates? I'm happy to work on it.
For example be_pusherror does not exist but it is included in chapter 9 of the documentation
With a little search for the functions marked BERRY_API in berry.h, the following functions are not found in the documentation:
- be_str2int
- be_str2real
- be_str2num
- be_classof
- be_ismodule
- be_iscomobj
- be_isderived
- be_toescape
- be_moveto
- be_pushbuffer
- be_pushclosure
- be_newmodule
- be_newcomobj
- be_newobject
- be_copy
- be_setname
- be_getmethod
- be_setsuper
- be_data_merge
- be_data_reverse
- be_iter_hasnext
- be_getmodule
- be_iseq
- be_isneq
- be_islt
- be_isle
- be_isgt
- be_isge
- be_returnvalue
- be_returnnilvalue
- be_getmodule
- be_iseq
- be_isneq
- be_islt
- be_isle
- be_isgt
- be_isge
- be_returnvalue
- be_returnnilvalue
- be_exit
- be_raise
- be_getexcept
- be_dumpvalue
- be_dumpexcept
- be_stop_iteration
- be_set_obs_hook
- be_set_ctype_func_hanlder
- be_loadmode
- be_loadlib
- be_savecode
- be_module_path
- be_loadmode
- be_loadlib
- be_savecode
- be_module_path
- be_module_path_set
- be_sethook
- be_setntvhook
In addition, the internal documentation (VM, language extension, etc) is practically non-existent and these things are one of the most important to increase its success among users (as it was for LUA).
If anyone is interested in this, I'd be happy to help.
I see, you mean the documentation of internal APIs for people who want to port or extend the language. This is not a priority on my side, you are more than welcome to contribute.
Maybe it's not a very frequent requirement, I understand, but it's important for the language to be used more widely and not only within Tasmota (I couldn't find other projects that include it).
It's a great language and I'd like to be able to expand its user base.
I will try to expand the documentation but I will surely need help in certain parts.
I'll be around here bothering :-)
@hiperiondev I have invited you to join the organization.
@hiperiondev I have invited you to join the organization.
Thank you very much for adding me to the project!
I think the next step would be to add the Doxygen headers to the project headers, if everyone agrees.
Those that are already in the documentation would be completed and those that would need to be documented would be left empty.
When this is complete the Read-the-docs generation will be added
I have added the documentation headers in berry.h. If there are no objections to the format I will continue completing with the information already available in the WIKI
Completed all documented functions. All non documented are marked as @brief (???)
Added base for Read the docs
I have merged the changes.
I will now continue to port the current documentation to Read-the-docs format.
Could someone complete the headers of the undocumented functions with a brief description of their use and operation?
Added base for Read the docs
Good morning, I would love to collaborate by including the documentation you prepare on the website.
With a theme of our own, of course.
All the documentation would be written with markdown, I just have to prepare a few things to include the theme in the website and prepare the environment.
Added base for Read the docs
https://berry.readthedocs.io/en/latest/Good morning, I would love to collaborate by including the documentation you prepare on the website.
With a theme of our own, of course.
All the documentation would be written with markdown, I just have to prepare a few things to include the theme in the website and prepare the environment.
Hi @diazvictor
Excellent news that more people join the project!
The documentation, a priory, should be the current one, both in English and Spanish.
It should be adapted to the multilingual Read-the-docs format.
It should also be integrated into the Doxygen documentation in the code.
Do you have experience in this?
Hi @diazvictor Excellent news that more people join the project! The documentation, a priory, should be the current one, both in English and Spanish. It should be adapted to the multilingual Read-the-docs format. It should also be integrated into the Doxygen documentation in the code. Do you have experience in this?
Yes I have experience, but I can't make a documentation generator based on the code, however I will eventually move your documentation into a section on the website as many languages have on their official pages.
The idea I had was to use a single documentation in both the wiki and the website written only with markdown.
I invite you to chat in our telegram group for convenience. Regards
The markdown documentation already exist:
English: https://github.com/berry-lang/berry/wiki
Spanish: https://github.com/HiperionDevelope/berry/wiki/
It's fine to start with that and then integrate doxygen. Read the docs supports it (not directly but it can).
Another way would be to port the internal documentation to Sphinx
@hiperiondev https://berry.readthedocs.io/en/latest/ this link is now dead
I recommend adding berry_conf.h to the documentation generation as well.
@hiperiondev https://berry.readthedocs.io/en/latest/ this link is now dead
Yes. Today I was working on the port of the documentation and the autodoxygen. I made another fork to not "dirty" the final commits.
It is not finished yet for auto-generation (I think I could finish it tomorrow)
But you can now create the documentation manually:
You can clone: https://github.com/sushisan/berry
And build it with: sphinx-build -E -c ./ -b html source/ build/html
In that repository, all the documentation entries in berry.h were completed and it indexes it correctly.
It's still not as nice as I would like but it works
I recommend adding berry_conf.h to the documentation generation as well.
My intention is to comment all the headers and index them later to complete the internal documentation.
OK, let me see how to use it in a CI workflow.
@skiars
There is a form problem for the automatic documentation. bntvmodobj, bntvmodule, bhookinfo are defined as typedef struct but have the same name for struct and type. While it is correct in C it is a style error and Doxtgen recognizes it as a duplicate.
The most common is that the type has the suffix _t in the name.
It would be desirable to correct it
The first part of the documentation is complete. It would only be necessary to modify the typedef to be able to automate it.
Now needs to be corrected in style and form but you can check it at https://github.com/sushisan/berry and manually build.
Completed porting. Now it needs to be polished and beautified
NOTE: ebnf codes in documentation do not validate grammar. Something is wrong
Do you like this theme for documentation?
https://github.com/TYPO3-Documentation/sphinx_typo3_theme
Demo:
https://typo3-documentation.github.io/sphinx_typo3_theme_rendering_test/
BTW: Sphinx support translations: https://docs.readthedocs.io/en/stable/guides/manage-translations-sphinx.html
NOTE: ebnf codes in documentation do not validate grammar. Something is wrong
The parser is single pass and hand crafted. Grammar is only for documentation purpose. What validation are you thinking about?
Grammar is marked as ``` ebnf. Sphinx is more strict for highlight and try to evaluate with a WARNING: Could not lex literal_block as "ebnf". Highlighting skipped.
Grammar is marked as ``` ebnf. Sphinx is more strict for highlight and try to evaluate with a WARNING: Could not lex literal_block as "ebnf". Highlighting skipped.
I don't think this highlight really matters.
@skiars There is a form problem for the automatic documentation. bntvmodobj, bntvmodule, bhookinfo are defined as typedef struct but have the same name for struct and type. While it is correct in C it is a style error and Doxtgen recognizes it as a duplicate. The most common is that the type has the suffix _t in the name. It would be desirable to correct it
good idea.
Grammar is marked as ``` ebnf. Sphinx is more strict for highlight and try to evaluate with a WARNING: Could not lex literal_block as "ebnf". Highlighting skipped.
Ah ok. I thought you wanted to validate the grammar. Indeed this is not strict ebnf
In the last commit the names of the types were corrected and the documentation for the automatic generation was completed in Read the docs. Not more warnings nor errors.
When the Merge will be accepted I will start to make it "beautiful"
You can see the provisional result in:
https://berry.readthedocs.io/en/latest/
Changed theme.
New preview:
https://berry-temp.readthedocs.io
Finished first stage