Add documentation to build the website/docs locally

[say4n]

Recently there was a conversation on IRC asking about how to build the docs as well as the website locally.

I think it is a good idea to have the instructions present on this repository itself. I'll work on it if I have some free time this week, otherwise, feel free to work on it. :)

[rcurtin]

@say4n agreed. It's not entirely trivial to build the website, because it uses all the doxygen output from every stable version. This can take some time to build.

In essence, the process is: put all versions of mlpack you want to build for in files/; the repository has a bunch already in there. You could remove old versions to save some time. Then, you can run _src/scripts/build-website-from-scratch.sh. I think there is a line at the end of that file that is specific to the setup on mlpack.org. After that, you can run _src/scripts/deploy-site.sh /path/to/deployment/ (with wherever you want to deploy it) and this will use Jekyll to build the site and deploy it.

I'm not sure anymore what the right Ruby setup is; there is probably some setup there that isn't done automatically.

The script that runs nightly to rebuild the mlpack-git documentation is _src/scripts/update-doxygen.sh, which also takes a deployment path as an argument. That is also integrated with the IRC log processing scripts, so I am not sure what will happen if those aren't there.

[NippunSharma]

@rcurtin, thanks I will follow these steps. Also thanks @say4n for opening this.

[NippunSharma]

@rcurtin, sorry for the late reply. I tried building the site, specifically I followed these steps:

1. installed jekyll and ruby.
2. cloned repo.
3. deleted versions before 3.4.2 in files/ directory.

4. ran build-website-from-scratch.sh. But, after step 4 there seems to be an error while generating markdown bindings, specifically the following error is thrown:

   CMake Error at /home/nippun/Desktop/mlpack.org/_src/mlpack-3.4.2/CMake/RunProgram.cmake:12 (message):
   Fatal error running
   /home/nippun/Desktop/mlpack.org/_src/mlpack-3.4.2/build/src/mlpack/bindings/markdown/generate_markdown:
   /home/nippun/Desktop/mlpack.org/_src/mlpack-3.4.2/build/src/mlpack/bindings/markdown/generate_markdown:
   symbol lookup error:
   /home/nippun/Desktop/mlpack.org/_src/mlpack-3.4.2/build/src/mlpack/bindings/markdown/generate_markdown:
   undefined symbol:
   _ZN6mlpack2IO8HasParamERKNSt7__cxx1112basic_stringIcSt11char_traitsIcESaIcEEE
   
   !

   What can be the problem here? Also, are there supposed to be any dependencies for markdown bindings?

[rcurtin]

This looks like an LD_LIBRARY_PATH issue... do you have a copy of mlpack installed on the system or is LD_LIBRARY_PATH set incorrectly? Basically I think the generate_markdown program is loading the wrong libmlpack.so, but I'm not exactly sure why.

[NippunSharma]

Ahh, yes I was working on the threadsafe issue where IO is modified and I remember setting LD_LIBRARY_PATH for that libmlpack.so, maybe the error is coming because of that. Let me build the mlpack main branch and set LD_LIBRARY_PATH there. I will let you know if that works 👍

[rcurtin]

Yep, hopefully that should help. :) There shouldn't be any extra dependencies to build the markdown bindings; if you're just building them in mlpack (and not via the scripts in this repository), you should end up with a file called doc/mlpack.md in the build directory after you run make markdown. That then gets processed by these scripts for the website. :+1: