LLVM Documentation - How does it get updated?

Over a month ago I submitted some patches to begin documenting PDB file format. These files are in llvm/docs/PDB. When I view the docs online though, they appear stale. Many of the pages are blank, containing only a file header. This matches up with my initial commit of the documentation, as I initially just created stub pages, but as I continued to improve the documentation, the website never got updated again.

There are at least 3-4 stale pages, but one easy one to see is http://llvm.org/docs/PDB/DbiStream.html. If you look in llvm/Docs/PDB/DbiStream.rst the file is 18K and contains a ton of information, but the page above is just blank.

I built the documentation target locally and when I view the locally generated documentation, everything is fine. So it is only a problem with the website.

Does anyone know how I can get this resolved or who i need to talk to?

Anton and/or Tanya, I think (cc'd).

Over a month ago I submitted some patches to begin documenting PDB file
format. These files are in llvm/docs/PDB. When I view the docs online
though, they appear stale. Many of the pages are blank, containing only a
file header. This matches up with my initial commit of the documentation,
as I initially just created stub pages, but as I continued to improve the
documentation, the website never got updated again.

Hi Zachary,

I can confirm the docs build normally on my machine, too. Did you
check when you first committed that the docs were good upstream?

I built the documentation target locally and when I view the locally
generated documentation, everything is fine. So it is only a problem with
the website.

I have Sphinx 1.5 here, but the website is using 1.4.5. What's the
version you're using?

I can see some warnings on my side, but there could be some errors on
the website, which would be the reason why they're empty.

My local warnings:

reading sources... [100%] yaml2obj
/home/rengolin/devel/llvm/worktree/docs/llvm/docs/CommandGuide/lit.rst:64:
WARNING: Duplicate explicit target name: "cmdoption-D".
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... WARNING: search index couldn't be loaded, but
not all documents will be built: the index will be incomplete.
done

I also found some CMake errors on that build that I'll fix. No other
doc was being updated for a while...:frowning:

cheers,
--renato

Yes when I first committed the docs were fine upstream. I think I even got 1 or 2 additional commits that I could see the changes of reflected on the website. At some point though, it just stopped updating (I don’t know which exact CL). I can find a date range of when things stopped being update if that would be helpful.

If I look at the PDB documentation now (which is rooted here) it’s all consistent with a certain point in time (again, I’d have to find the exact CL), but nothing after that point in time ever made it in.

I'm betting it was around the time we made GCC 4.8 the minimum requirement... :slight_smile:

Generating makefiles
CMake Error at cmake/modules/CheckCompilerVersion.cmake:12 (message):
  Host GCC version must be at least 4.8!
Call Stack (most recent call first):
  cmake/config-ix.cmake:14 (include)
  CMakeLists.txt:582 (include)

However, the GCC on that machine is 4.9.4, so I have no idea why the error...

Unfortunately, we don't have a good way to capture errors with the
docs builds, so it ends up as "whoever notices first".

I'll speak to Anton and Tanya about this.

cheers,
--renato

Just a suggestion: Setting up the documentation build up as a buildbot (or jenkins) job would make it transparent what happens and what errors are occuring on the build machine...

- Matthias

There is already a bot that builds documentation. Turns out it was down for a while, but I contacted the owner and got it back up a few weeks ago. That buildbot is working fine, it just doesn’t upload anything, only builds.

Those bots are only doing validation, not pushing the docs anywhere.
The process that updates the docs is completely separate.

This is a really fragile publishing mechanism and one that is giving
us headaches for a long time. I think we need to sit down and fix
this.

My initial proposal is to have the buildbot on the same machine as the
docs, and to have a very small cloud machine as our docs front-end.
But that'll depend on how the foundation is handling this already.

I started a discussion about this on the llvm-admin list, lets see how it goes.

cheers,
--renato