Granularize the wiki

[tobozo]

Hello and thanks for this great project :+1

I know this is 2020 and most devices are modern, but this is 2020 and basic documentation should not look like it's being thrown at the user with an agricultural fork.

/!\ Do not visit this wiki page unless you have some time and bandwidth to lose

Visiting this page will:

• make the browser freeze for a few seconds
• saturate the http pipeline with 3361 requests, downloading only 8MB of binaries
• finish loading after 2 mn (and that's using a 350MBps fiber connection on a core I7 desktop PC)
• serve links using only target=self (to make sure you have to come back and live this again ?)
• eventually get your github account banned for one hour

This effect is very unfair both for this project and for the users.

A few easy solutions come to mind, but highly depend on how the wiki contents is generated.

• Split the font list in smaller chunks
• Paginate the fonts list
• Move the fonts documentation to a github page (e.g. https://olikraus.github.io/u8g2) and either:
  • Use JavaScript for image lazy loading
  • Use a CSS sprite sheet
• Apply a mix of the above solutions

[olikraus]

You might be right. But I am a spare time maker/programmer. I do not have much time for this project. As a consequence, most pages are generated, including the fontlist.
Over the year users expected new fonts, so the fontlist constantly increased, but I did not restructure the fontlist itself.
However there are some improvements:
There is a pdf version here:
https://github.com/olikraus/u8g2/blob/master/doc/u8g2fntlistall.pdf
There is also the requested granularization:
https://github.com/olikraus/u8g2/wiki/fntgrp

Split the font list in smaller chunks

done from my perspective

Paginate the fonts list

also done

Move the fonts documentation to a github page

What is wrong with the wiki page here?

Use JavaScript for image lazy loading & Use a CSS sprite sheet

Why shell I do this? I have used proper HTML. I do not have the time to improve web technologies.
If they do not work as expected, then the question is, why they are offered.

I am getting tired of people complaining about this and that.

• This feature is missing u8g2
• u8g2 code is to large
• u8g2 code is not correct formated
• u8g2 does not include a full featured menu system
• u8g2 does not explain how to write software
• u8g2 does not work in my unknown, rarly used xyz environment
• Documentation is too less
• Documentation is too large
• Documentation does not use latest web technologies

I know, you made some nice suggestions. All good, but I will not implement this.
I already moved everything from mercurial to git and from google code to github.
If github wants to banish this project, fine... let them do it, it is their web space.
I am sorry if I have misused the great github service here, but I feel myself unable
to spent time into advanced web performance improvements.

I am a electronics engineer and embedded software developer and not a web developer.
All this is for free, If you don't like it. either improve it or don't use it.
And if github doesn't like it, let's shut it down. I will be happy to spent more time on electronics ;-)

[tobozo]

Being a spare time programmer and library maintainer myself, I'm very enthusiastic about your work on u8g2, and I'm quite ready to contribute with whatever issue I create.

I already moved everything from mercurial to git and from google code to github

I still have a few sourceforge projects myself, some are using CVS 🤣

What is wrong with the wiki page here?

It is loading more than 3000 assets, I know HTML allows this, but I want to help with mitigating the effects of visiting that page.

If a copy of the png files from the fntlistall page are also available on github pages (a domain ending in .github.io) the ban effect can be mitigated by providing the full URL to the images instead of a relative path.

Copying the PNG files on github pages can be automated with github actions or travis, and only requires you check a box in your project's settings before adding one .yml file where the behaviour is described.

I can help with all that but I can't just send a pull request without you approving the idea first.

[olikraus]

Sounds like a good idea with minimal effort. However I have no idea how to create a github.io page.

[tobozo]

First create a special branch (e.g. "gh-pages") then go into the settings tab of your repository to find the " Github pages" options and select that branch.

Now whatever files you will push on that branch (e.g a copy of the assets in the u8g2.wiki folder) will be available at https://olikraus.github.io/u8g2/ so it's okay to eventually remove the project files before pushing manually.

Automating with travis requires creating a github personal access token, but the process can also be scripted:

• git checkout master
• *generate documentation using your existing method
• *copy the image assets in a temporary folder (outside the repository)
• git checkout gh-pages
• *delete all existing files in the project directory
• *copy assets from temporary folder to project directory
• git add . & git commit -m "updated assets" && git push -u origin gh-pages

If you don't want to maintain another script and you're okay to go with travis, here's a travis.yml example:

sudo: false
branches:
  only:
    - master
script:
  - /tools/doc/documentation_builder.sh # << adjust this
deploy:
  provider: pages # << this tells travis to publish to github pages
  skip_cleanup: true
  verbose: true # << for debug
  local_dir: html # << travis will copy the contents of the "html" folder to github pages
  github_token: $GH_REPO_TOKEN # << github.com personal token must be configured at travis-ci.org
  on:
    branch: master # only update github pages when {pull request, push, release} on main branch

[olikraus]

Thanks for your effort. I have a basic question here: What is the advantage of having a new branch. Can't i simply use the master branch?

If I understand you suggestions correctly, the branch will contain a complete different folder structure. We will never do a merge again, right? So the branch is just a parallel folder structure for github pages.

[tobozo]

Yes I suppose you can use the master branch, but that's only if it already has the generated contents.
Since you have a lot of automations in your build process it's probably better to keep that documentation build history out of the main branch.

So the branch is just a parallel folder structure for github pages.

yep, it's never merged with the main branch indeed

[tobozo]

Followup: travis.org will end in december 2020, projects migrated to travis.com will stay free for open source repositories but "free" it an opt-in situation, so it lands in the same "default billable unless public" perimeter as github actions.

Here's an example using the deploy-to-github-pages action:

name: Build and Deploy Documentation to gh-pages
on: [push]
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 🛎️
        uses: actions/checkout@v2.3.1
        with:
          persist-credentials: false

      - name: Install and Build 🔧 
        run: |
          /tools/doc/documentation_builder.sh # << adjust this

      - name: Deploy 🚀
        uses: JamesIves/github-pages-deploy-action@3.7.1 # << the deploy plugin
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH: gh-pages # The branch the action should deploy to.
          FOLDER: html # The folder the action should deploy.
          CLEAN: true # Automatically remove deleted files from the deploy branch

[olikraus]

today I checked options to implement css sprite sheets, but github markdown does not allow any style tags or attributes. They are removed by the sanitizer (https://github.com/github/markup#github-markup).

[tobozo]

hey @olikraus and happy (un)boxing day :-)

The limitation you're mentioning is for markdown contents only, but the *github.io pages can deploy any type of content (html, js, css, images and any other static asset).

So a css spritesheet can be used, but only when published on the *github.io hosting site, and deployed using a workflow for publishing static contents such as html/css(/js) and images.

Keep in mind that many suggested gh-pages workflows will use markdown documents as templates to generate static content for *github.io: indeed these aren't the workflows you'r looking for 🤖

[olikraus]

I have splitted the fntlistall page into four sub pages. Hope this helps.

[tobozo]

I don't get the abuse page anymore after loading the font list, so it's a win, thanks!