berry
berry copied to clipboard
Reworked documentation structure, added Docker integration
Hi! First of all thank you for taking the time and publishing the Berry! I've recently took a stab at porting Berry to a custom firmware for ESP32 and so far I'm quite enjoying it!
The only part that felt somewhat confusing was the documentation so I've spent a weekend trying to figure out what would help me in this journey. This pull request is an initial result of that. I'll try to describe what I've done and my rationale behind some of the decisions I've made as I think that those are more important than the actual changes I'm proposing.
In a random order:
- I've dropped the Spanish language - I kinda feel like it's difficult enough to keep one language in sync with the code, let alone multiple ones
- I've added Docker integration for building both Berry executable and Berry documentation - kinda feels like a more modern way of specifying the runtime dependencies for code (this will still require uploading to Docker Hub though)
- I've added a "watcher" script so one can edit the code and the documentation will be rebuilt "live"
- I've adjusted some paths in the documentation sources so they're more aligned with the recommended templates - I have not tested them on
readthedocsthough - I've moved some content from
README.mdto the actual documentation - I'm a huge believer that almost everything has it's place and that it's much easier to keep stuff in sync when we limit the number of places we keep things in - I've added a "favicon" version of the logo and moved logos to the
docsdirectory as those aren't strictly a "top level" kind of data to me - I've sorted some listings alphabetically (like the
requirements.txtand extension lists) - I've reworked the main page of the documentation - there's a logo there now and a preface was moved here
- I've divided the documentation in three sections - language user, vm user, and a language developer as I fell like those are three "levels" for the Berry users and we kinda shouldn't be confusing them with giving them all the data at once.
I kinda feel like more can be done but this weekend is almost over and I wanted to start the discussion as early as possible. Some ideas for the future:
- Sphinx has support for "out of tree" html files so maybe the online interpreter can be built-in and more of the landing page integrated here (possibly all of it so it makes maintenance easier)
- Add Github Actions workflows that will build Berry and run
testall.beso we can add "builds passing" icons that always convey confidence (bonus points for a license icon) - Add a workflow that will test a C++ build (I've found some issues in it and will be sending another PR some time soon)
And some other, even smaller items. Please let me know if you want to me to tackle those and I'll try to figure out some free time for that.
To sum up - I've really enjoyed working with this project and I hope that you'll find my suggestions valuable.
-- Have a wonderful day pidpawel
I do not agree with removing the Spanish translation. Berry is a great language but with a VERY limited number of users, translating the documentation is a must to encourage its use. For the maintenance I have already offered myself (in fact I am the original translator). For the rest of the modifications I should review them but, a priori, I am not opposed
There is already a port to ESP32 that I made a while ago. Maybe it can help you:
https://github.com/hiperiondev/esp32-berry-lang
It would be very helpful if you could put this documentation in a directly readable form somewhere for review (perhaps https://readthedocs.org/)
I'm putting my question back here as well. How do we copy the content of the latest updates in the wiki to reflect to the readthedocs pages?
I propose to move to berry_doc, and not interfere with the code repository.