Page MenuHomeFreeBSD

Add HTML targets to doc/documentation/Makefile
Needs ReviewPublic

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

Details

Reviewers
ceri
Group Reviewers
doceng
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 Skipped
Unit
Unit Tests Skipped

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…