Page MenuHomeFreeBSD

Freebsd doc cross-platform build
Needs ReviewPublic

Authored by fel1x.mintchoco.development_gmail.com on May 8 2021, 2:10 PM.

Details

Reviewers
carlavilla
ygy
Group Reviewers
docs
Summary

I figured out they way to build freebsd-doc on macOS and Linux

Test Plan

On macOS, building with bmake command works fine for hugo. (Tested Freebsd Handbook with images)

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

bcr added a subscriber: bcr.

Adding Sergio, as I think this might interest him.
Having a way to build our docs on other platforms is nice and might bring in some new contributions.

documentation/content/en/books/fdp-primer/doc-build/_index.adoc
55

New sentence, new line.

131–132

New sentence, new line.

documentation/content/en/books/fdp-primer/overview/_index.adoc
87

s/differeces/differences/

A thought: could we also mention that we need to install some dependencies and they may have different package names?

documentation/content/en/books/fdp-primer/doc-build/_index.adoc
55

difference*
space before "("

documentation/content/en/books/fdp-primer/overview/_index.adoc
87

syntax*

Can someone review or commit my new diff file?

I’ll take this. Thanks for the patch

This is indeed a good start, though I quickly tried it on Ubuntu and didn't have any luck - https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=255804

@fel1x.mintchoco.development_gmail.com, did you have to do anything else to make it work, except for switching to use make?

On macOS, documentation works.


I putted the screenshot of terminal and the page of localhost:1313

Ok, no objections to moving this forward - if we find more details for other platforms in the future, we can always improve it then.

Today, I tried on Linux. I succeeded on Red Hat 8 on VMware Fusion 12. However, I had to install bmake hugo through homebrew and asciidoctor, asciidoctor-pdf, rouge through gem. Also, I had to make symbolic links of programs because in those programs are not instlled in /usr/local/bin/. Maybe this works in some distributions but not for others. I will try on other Redhat derivatives, Debian derivatives, and SUSE derivatives in a near future.
Here are some screenshots.


bmake and hugo technically works on linux. However, many distributions don't install packages in /usr/local/bin, problem with permissons. On Redhat side, only RHEL works, not fedora. On Debian side, Ubuntu doesn't work. The problem is permission in both cases, but there are other problems when I run bmake with root.

bmake and hugo technically works on linux. However, many distributions don't install packages in /usr/local/bin, problem with permissons. On Redhat side, only RHEL works, not fedora. On Debian side, Ubuntu doesn't work. The problem is permission in both cases, but there are other problems when I run bmake with root.

Thanks for all the testing results! We indeed should make the doc project more accessible for more platforms, and am happy to continue the discussions somewhere else (any insights on https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=255804 ?).

Again, this revision looks good to me, and @carlavilla seems to already be taking care of it ;)