Render Documentation to static website #17

Closed
opened 2 years ago by lhinderberger · 13 comments

This is a issue for tracking the progress on creating a lean and friendly statically-generated website for our Documentation.

I volunteered to make a prototype in https://codeberg.org/lhinderberger/codeberg-docs-prototype and will make a pull request here once #15 has been decided on.

I will post updates about major progress here.

Feel free to put questions or suggestions to the new prototype here or in the issue tracker of the repo above.

Ref: #7, #13

This is a issue for tracking the progress on creating a lean and friendly statically-generated website for our Documentation. I volunteered to make a prototype in https://codeberg.org/lhinderberger/codeberg-docs-prototype and will make a pull request here once #15 has been decided on. I will post updates about major progress here. Feel free to put questions or suggestions to the new prototype here or in the issue tracker of the repo above. Ref: #7, #13

A first look at the design. Suggestions for improvement are welcome!

A first Screenshot

From: https://codeberg.org/lhinderberger/codeberg-docs-prototype/src/branch/master/doc/screenshot.webp

A first look at the design. Suggestions for improvement are welcome! ![A first Screenshot](https://codeberg.org/lhinderberger/codeberg-docs-prototype/raw/branch/master/doc/screenshot.webp) <sub>From: https://codeberg.org/lhinderberger/codeberg-docs-prototype/src/branch/master/doc/screenshot.webp</sub>
n commented 2 years ago
Collaborator

Looks good! Using Rubik-Regular instead of Rubik-Light looks better IMO.
Codeberg Documentation Prototype Rubik-Regular.png

Looks good! Using Rubik-Regular instead of Rubik-Light looks better IMO. ![Codeberg Documentation Prototype Rubik-Regular.png](https://codeberg.org/attachments/b70c0f4d-f397-45b7-aaef-07b356d4d302)

The menu definitely looks better with Rubik Regular. With Light is was hard to read.

I personally think the block of text looks better in Light though 😉

The menu definitely looks better with Rubik Regular. With Light is was hard to read. I personally think the block of text looks better in Light though 😉

The most recent commit now features an automatically generated menu from the first two hierarchy levels of the files in src/articles. It also renders responsively across desktop and mobile devices.

It is currently using the menu structure as seen in the screenshots, but it can be adapted to the structure of #16 or vice versa when adding actual documentation content.

This means all essential major functions (except i18n) have now been implemented, with some stylesheet adjustments, meta tags and links still missing.

The most recent commit now features an automatically generated menu from the first two hierarchy levels of the files in `src/articles`. It also renders responsively across desktop and mobile devices. It is currently using the menu structure as seen in the screenshots, but it can be adapted to the structure of #16 or vice versa when adding actual documentation content. This means all essential major functions (except i18n) have now been implemented, with some stylesheet adjustments, meta tags and links still missing.

v1 is now feature-complete on the technical side (i18n can be implemented in v2).

It's now blocked by #15, lhinderberger/codeberg-docs-prototype#2 and (depending on whether the documentation site shall be entirely under AGPLv3) Codeberg/Design#16

v1 is now feature-complete on the technical side (i18n can be implemented in v2). It's now blocked by #15, https://codeberg.org/lhinderberger/codeberg-docs-prototype/issues/2 and (depending on whether the documentation site shall be entirely under AGPLv3) https://codeberg.org/Codeberg/Design/issues/16

The current state of the prototype can be tested at https://cb-docs-prototype.lhinderberger.com/

The current state of the prototype can be tested at https://cb-docs-prototype.lhinderberger.com/
Owner

With #16 merged, what is needed to get this live?

With #16 merged, what is needed to get this live?

With #16 merged, what is needed to get this live?

The Bug in lhinderberger/codeberg-docs-prototype#2 needs to be fixed and the license of the logo (Codeberg/Design#16) should be clarified so that the site can be under CC-BY-SA (I'm currently working on looking up how other projects handle their logos).

Then I will integrate that into the prototype, do some last polishing and write a PR here.

> With #16 merged, what is needed to get this live? The Bug in https://codeberg.org/lhinderberger/codeberg-docs-prototype/issues/2 needs to be fixed and the license of the logo (https://codeberg.org/Codeberg/Design/issues/16) should be clarified so that the site can be under CC-BY-SA (I'm currently working on looking up how other projects handle their logos). Then I will integrate that into the prototype, do some last polishing and write a PR here.
Owner

We could also use a common service such as readthedocs etc ... I guess I'd prefer that. The theme looks cool, nevertheless. It might get ported to this?
I don't see the need for so many different static site generators. I mean - I love them, but it makes it harder to maintain stuff in the future if the people who are setting it up today are not available tomorrow anymore ... Codeberg already uses Pelican for the blog, and read the docs is an easy standard. I'd rather use one of them.

We could also use a common service such as readthedocs etc ... I guess I'd prefer that. The theme looks cool, nevertheless. It might get ported to this? I don't see the need for so many different static site generators. I mean - I love them, but it makes it harder to maintain stuff in the future if the people who are setting it up today are not available tomorrow anymore ... Codeberg already uses Pelican for the blog, and read the docs is an easy standard. I'd rather use one of them.

The main advantages of the approach using Eleventy are its simplicity and flexibility, as well as the fact that we can very easily self-host the resulting page.

The site as it is right now was built completely from scratch within 3-4 days, and the resulting source code is small and easy to understand. The "theme" basically consists of one Nunjucks template, one CSS file and a bit of JavaScript for the mobile menu - all less than 100 lines. This is easy enough for any web developer - experienced or beginner - to understand (and Eleventy is also very easy to learn) so I don't think we'll have any trouble finding a maintainer if I should be unavailable.

Eleventy is a pleasure to work with, because it tries its best to get out of your way - you rarely have to "fight the framework" - and it's very customizable. From a developer perspective, this simple setup means you can be productive in no time, due to being able to quickly gain a complete understanding of what is going on.

Lastly, it's very easy to self-host. It's basically npm run build and cp -r _site/* /var/www/html/something.

As for ReadTheDocs on the other hand: It's a commercial service under U.S. law and hosted on Microsoft Azure. According to their privacy policy they use Google Analytics. Is that really what we want for Codeberg Docs? The closest alternative to using their service would be self-hosting documentation generated by Sphinx, which would be yet another site generator.

For the sake of argument, it would be possible to self-host our own RTD instance, as is described in their documentation. Now does that really sound like an easy-to-use alternative, compared to the deployment of a static site? 😉

The main advantages of the approach using Eleventy are its simplicity and flexibility, as well as the fact that we can very easily self-host the resulting page. The site as it is right now was built completely from scratch within 3-4 days, and the resulting source code is small and easy to understand. The "theme" basically consists of one Nunjucks template, one CSS file and a bit of JavaScript for the mobile menu - all less than 100 lines. This is easy enough for any web developer - experienced or beginner - to understand (and Eleventy is also very easy to learn) so I don't think we'll have any trouble finding a maintainer _if_ I should be unavailable. Eleventy is a pleasure to work with, because it tries its best to get out of your way - you rarely have to "fight the framework" - and it's very customizable. From a developer perspective, this simple setup means you can be productive in no time, due to being able to quickly gain a complete understanding of what is going on. Lastly, it's very easy to self-host. It's basically `npm run build` and `cp -r _site/* /var/www/html/something`. As for ReadTheDocs on the other hand: It's a commercial service under U.S. law and hosted on Microsoft Azure. According to their privacy policy they use Google Analytics. Is that really what we want for Codeberg Docs? The closest alternative to using their service would be self-hosting documentation generated by Sphinx, which would be yet another site generator. For the sake of argument, it would be possible to self-host our own RTD instance, as is described [in their documentation](https://docs.readthedocs.io/en/stable/custom_installs/local_rtd_vm.html). Now does that really sound like an easy-to-use alternative, compared to the deployment of a static site? 😉

lhinderberger/codeberg-docs-prototype#2 has been resolved.

That means that the licensing of the logo is the only thing left before everything can be neatly integrated.

If you're interested in advancing that discussion, feel free to join in on Codeberg/Design#16 :)

https://codeberg.org/lhinderberger/codeberg-docs-prototype/issues/2 has been resolved. That means that the licensing of the logo is the only thing left before everything can be neatly integrated. If you're interested in advancing that discussion, feel free to join in on https://codeberg.org/Codeberg/Design/issues/16 :)

I have now created a Pull Request with the finished basic static site and I have added issues for all open questions that arose during the development of the prototype.

I have now created a Pull Request with the finished basic static site and I have added issues for all open questions that arose during the development of the prototype.
Owner

great, give us a few days to prepare setup for deployment!

great, give us a few days to prepare setup for deployment!
hw closed this issue 2 years ago
Sign in to join this conversation.
No Milestone
No Assignees
4 Participants
Notifications
Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Codeberg/Documentation#17
Loading…
There is no content yet.