Add HTML targets to doc/documentation/Makefile

[blackend]

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.

[dbaio]

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?

[blackend]

In D30718#690992, @dbaio wrote:

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.

[dbaio]

In D30718#691109, @blackend wrote:

In D30718#690992, @dbaio wrote:

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

[dbaio]

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/

[ceri]

In D30718#691132, @dbaio wrote:

In D30718#691109, @blackend wrote:

In D30718#690992, @dbaio wrote:

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…

[blackend]

Add support for stylesheets.

[blackend]

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.

[blackend]

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

[ceri]

documentation/Makefile

68

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

75

Same here.

[ceri]

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.

[blackend]

• s/without/with only comments
• Add a check before building books TOC.

[ceri]

Thanks!