Render Documentation to static website #17

lhinderberger commented 2020年07月28日 20:17:48 +02:00

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

lhinderberger commented 2020年07月29日 00:33:59 +02:00

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!  _{From: https://codeberg.org/lhinderberger/codeberg-docs-prototype/src/branch/master/doc/screenshot.webp}

n commented 2020年07月29日 11:30:36 +02:00

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. 

lhinderberger commented 2020年07月29日 18:52:21 +02:00

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 😉

lhinderberger commented 2020年07月30日 21:52:55 +02:00

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.

lhinderberger commented 2020年07月31日 22:15:33 +02:00

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

lhinderberger commented 2020年07月31日 22:31:59 +02:00

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/

hw commented 2020年08月02日 16:38:43 +02:00

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

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

lhinderberger commented 2020年08月02日 16:43:25 +02:00

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.

fnetX commented 2020年08月03日 12:00:05 +02:00

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.

lhinderberger commented 2020年08月03日 19:20:35 +02:00

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 commented 2020年08月04日 16:15:34 +02:00

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 :)

lhinderberger commented 2020年08月13日 12:55:38 +02:00

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.

hw commented 2020年08月16日 20:38:58 +02:00

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

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