Idea: switch from Nikola to Hugo

[hamoid]

I just went through the process of setting up Nikola to build and run a local copy of the OF website.

Compilation speed

I was slightly surprised to discover that in "autobuild" mode, it takes 75 seconds in my i7 laptop to rebuild the site even if I just changed one character in a markdown file. This is not very encouraging towards doing a lot of improvements to the documentation.

For my own site (with hundreds of posts and hundreds of megabytes of images) I had similar experiences when using Jekyll, but with hugo a rebuild takes milliseconds, and the page even reloads automatically in the browser. So I can do "live coding" of my site in markdown.

Installation process

Hugo is a single binary (FOSS) built with Go, available for Linux, Mac and Windows. Nikola requires Python 3, virtualenv, pip and has many dependencies and thousands of files. Installing hugo is probably more straightforward, since it's just one brew or apt-get package.

Challenge

If the change is ever done, the challenge might be to port the design and keep all URLs intact, write new documentation explaining how to use hugo, update the scripts (basically hugo to build the site before uploading it, and hugo server while developing to create an http server that auto reloads the pages)

[arturoc]

The most slow is building the documentation since it requires a lot of parsing of all the markdown files. It's not the default rendering engine of nikola but our own to parse the autogenerated markdown files to html

there's a way in nikola to specify dependencies so it only rebuilds the files that change which it's working for the whole site except for some parts of the docs so finishing that should speed up things considerably.

the main problem porting the site to anything that is not python is that all the code to parse the docs as well as the libraries we use to parse the code to convert it to markdown are written in python and it would be a ton of work to port to another language

[hamoid]

Trying to understand the issue: so there's python scripts that scan .cpp/.h files, extract data and produce markdown files, and later Nikola converts those markdown files into html? And it's those python scripts that take some time to run? If that's the case, couldn't it be cached? Because if I change the markdown file, the .cpp/.h files have not changed, so no need to look at source code files again, or?

[arturoc]

yes the cpp/h -> markdown process is cached and never really runs when building the site. what runs is the markdown -> html which is a custom plugin for nikola that creates all the indices and content of the documentation.

That's not parsing completely ok the dependencies so when any documentation file changes it rebuilds all the documentation section but could be improved so it only built the affected pages (ie: the indices and the page for that content itself)