Page MenuHomeFreeBSD

Add HTML targets to doc/documentation/Makefile
ClosedPublic

Authored by blackend on Jun 10 2021, 4:40 PM.

Details

Summary

Addition of HTML targets allowing the build of HTML version of docs with selection of the language.
For example:
make DOC_LANG="en,fr" html-books
or
make DOC_LANG="it" html-books html-articles

This uses directly asciidoctor not hugo.

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Not Applicable
Unit
Tests Not Applicable

Event Timeline

blackend created this revision.
blackend added a reviewer: ceri.

This is nice to test/build a single document, only issue is that it won't use our template/css.
Just to know, these html's will be used where?

This is nice to test/build a single document, only issue is that it won't use our template/css.
Just to know, these html's will be used where?

Still rough around the edges, I'm going to add the missing css part.
The aim of this addition is to be able to build one localized version of the docs without the need to build every languages. This is useful for misc/freebsd-doc-* ports.

This is nice to test/build a single document, only issue is that it won't use our template/css.
Just to know, these html's will be used where?

Still rough around the edges, I'm going to add the missing css part.
The aim of this addition is to be able to build one localized version of the docs without the need to build every languages. This is useful for misc/freebsd-doc-* ports.

Right.

I was wondering if we can do this with Hugo, using the same template as the current documents and all the information in the front-matter.

There is an option for disable languages:

Building only en:

$ HUGO_DISABLELANGUAGES="es pt-br de ja zh-cn zh-tw ru el hu it mn nl pl fr bd da ko tr" make
...

                   | EN
-------------------+------
  Pages            | 173
  Paginator pages  |   0
  Non-page files   |   0
  Static files     | 928
  Processed images |   0
  Aliases          |   0
  Sitemaps         |   1
  Cleaned          |   0

Total in 15458 ms

Building only pt-br:

$ HUGO_DISABLELANGUAGES="en es de ja zh-cn zh-tw ru el hu it mn nl pl fr bd da ko tr" make
...
Error: cannot disable default language "en"

default language cannot be disabled at this moment.
https://github.com/gohugoio/hugo/issues/6377

Other idea is to create additional Hugo config, this way many options can be disabled when building the port version.
documentation/config/_default --> documentation/config/port-xxx

It seems all documents that were split has a single/full html in /book/, this is new for me. I noticed after seeing this patch.

https://docs.freebsd.org/en/books/porters-handbook/book/
https://docs.freebsd.org/en/books/developers-handbook/book/

This is nice to test/build a single document, only issue is that it won't use our template/css.
Just to know, these html's will be used where?

There is an option for disable languages:

Building only en:

$ HUGO_DISABLELANGUAGES="es pt-br de ja zh-cn zh-tw ru el hu it mn nl pl fr bd da ko tr" make

That seems really counter-intuitive when we have DOC_LANG. Driving this from DOC_LANG seems a good candidate for the list we talked about!

default language cannot be disabled at this moment.
https://github.com/gohugoio/hugo/issues/6377

And that just feels like another reason I don’t like Hugo. It seems to bring only problems for us. Also for the list…

Add support for stylesheets.

In D30718#691165, @ceri wrote:

default language cannot be disabled at this moment.
https://github.com/gohugoio/hugo/issues/6377

And that just feels like another reason I don’t like Hugo. It seems to bring only problems for us. Also for the list…

Yes. Hugo is aimed at websites/blogs generation, we're trying to use it for something else.

Update to last tree revision.
Add many inputs from Ceri.

documentation/Makefile
68

Apologies - this is my bug but this should read "with only articles" rather than "without articles".

75

Same here.

documentation/Makefile
118–125

We need to wrap this in a check that BOOK_LANGS is not empty, otherwise we get a failure with DOC_LANG=tr, for example.

  • s/without/with only comments
  • Add a check before building books TOC.
This revision is now accepted and ready to land.Jul 13 2021, 11:12 AM