Documentation for Windows

[kerimoyle]

Hi all I'd like to add some (more) Windows-only stuff to the documentation, specifically:

1. removing the MEMCHECK and COVERAGE tags from CMake as they don't work on Windows
2. removing some of the links to libxml2 to make it clearer that in Windows you have to download the prebuilt binary from the cellml site
3. adding errors which occur if you have a mix of 32 and 64 bit versions
4. need to restart computer before building libcellml (think it affects doxygen)
5. also need to manually install graphviz (https://graphviz.gitlab.io/_pages/Download/Download_windows.html​) and add to path.

Any thoughts?

[agarny]

• removing the MEMCHECK and COVERAGE tags from CMake as they don't work on Windows

I would probably be in favour of that and not only for Windows, but also macOS since memory check and coverage only work properly on Linux.

• removing some of the links to libxml2 to make it clearer that in Windows you have to download the prebuilt binary from the cellml site

I would agree that the documentation could probably be improved when it comes to libxml2 on Windows.

• adding errors which occur if you have a mix of 32 and 64 bit versions

A mix of 32 and 64-bit versions of what? If we are talking about executables then that mix shouldn't matter (as @hsorby mentioned at some point). However, if we are talking about a mix of 32 and 64-bit versions of libraries, then yes it will clearly break things. This being said, people should know that you can't mix 32 and 64-bit versions of libraries.

Still, I guess it can't harm having such a warning (assuming we are talking about libraries as opposed to executables).

• need to restart computer before building libcellml (think it affects doxygen)

I believe this very much depends on how things get configured, no?

• also need to manually install graphviz (https://graphviz.gitlab.io/_pages/Download/Download_windows.html​) and add to path.

I have never needed to install Graphviz when it comes to libCellML. Why do you need it?

[hsorby]

1. Definitely, should have its own issue not solely a documentation problem.
2. More documentation is always better. But I would like to remind people that you don't have to use the pre-built binaries it is something you can do, that is in our opinion, the easiest thing to do. Other options include building it yourself from various repositories one of which is the repository available from opencmiss-dependencies.
3. I think a note on reminding users that a 32 bit Python can't be used for creating Python bindings for a 64 bit library (or vice versa) would be sufficient.
4. I would have to check this I wouldn't want to tell people that they need to restart when they actually don't.
5. I take it this is for the generation of the documentation on windows using Sphinx? Another thing I would like to check.

[kerimoyle]

1. Present elsewhere now I believe ... ?
2. I originally tried going down the rabbithole of building it myself (as missed the prebuilt download link in the forest of other ones). I'm not sure whether it's my old-ish Windows machine that's not been set up well for coding or what, but there seemed to be so many other dependencies that conflicted with what I had that I gave up. I'll make sure it's clear that people can build their own in they prefer it though.
3. Yes, a reminder or example of the error would be enough - mostly because it causes a non-helpful CMake statement which took a long time to figure out.
4. Agreed ... but not sure how to check?
5. Yes, is used by Sphinx for drawing the class dependency trees (I think?) in the documentation.

I'll have a go at this tomorrow.

[nickerso]

for 4) I think it is enough to have a standard "you may need to restart windows" if things don't work. You can almost guarantee that some people will need a restart and some will not :) Pretty sure there is no foolproof way to check it across the range of Windows configurations that people will have...

[kerimoyle]

Is there a general policy (too strong a word) that every time something is mentioned in the documentation it should be hyperlinked somewhere? Personally I find this distracting, and it makes finding the real links so much more difficult ... am I ok to remove some of them?

[MichaelClerx]

Could you give some examples?

[kerimoyle]

eg: https://libcellml.readthedocs.io/en/latest/dev_building.html "Windows" links to the wikipedia page ... are not really adding value? "LibXml2" links everywhere were really hard to get past. I wanted to find the 64bit precompiled binary, but because you have to click each of these links to find out what's behind them, I pretty soon came to the conclusion (wrongly) that I was supposed to have built my own version.
"CMake" links in the middle of text explaining how to use CMake once it's already been downloaded and installed.

I guess it just gives the impression that there's more useful info behind the link that need to be read, which isn't the case. It would be more helpful (I think...) to have a list of links somewhere at the start, and then to just remove the others from the text. If they add value then they deserve to be highlighted. If they don't add value then maybe they shouldn't be there?

[MichaelClerx]

Makes sense! If we could have them as links the first time they occur that'd be fine by me. Also occasional links to relevant pages like how to install, how to make X work with Y, that kind of thing. Then again, I certainly wouldn't click every link in a piece of documentation when reading :D

[nickerso]

Sphinx allows the definition of a glossary and then cross-references to that - could be a way to achieve this? In general I agree that there are far too many links that are not particularly helpful - but we also need to be careful as any section could be linked to directly externally...

[agarny]

The first time I went through the documentation, I had to look up for different things that were mentioned in the documentation. So, I eventually decided to add links here and there, but... I agree that it has gone out of hand.

I am definitely happy for the number of links to be reduced, as long as there is at least one link for a given resource and that that link is easy to access.

[kerimoyle]

I've had a go now ... in general I've tried to have one "definition" for each package at the start of the paragraph which uses it. Throughout the rest of the text I've tried to follow the web best-practice idea of the link text describing what it contains (rather than links that say "go here for something good" go for "go to the something good page" instead so that screen-readers can navigate better).

I see that there's already a glossary in existence as @nickerso suggested, but so far it has only one term in it! Scope for extension there ... ;)

I've created a pull request just so that this is in the mix ... see #335

[kerimoyle]

Having read the more recent updates to the future work/roadmap stuff about installers, I think this is going to be out of date before it even gets there! Will stop working on it for now...