Update prefix documentation

[chiphogg]

Following up to clean up from #300.

[gitpod-io[bot]]

[mpusz]

Let's wait to accept this until the discussion in #374 is resolved.

[mpusz]

Also, we will probably need some magnitude-specific docs as well.

[mpusz]

This needs another update...

[mpusz]

Also, the rest of the documentation should be reviewed and updated where necessary + a dedicated subchapter on the magnitude in the units chapter would be useful (also the links to the bugs resolved with this change may be useful as ISO will ask why we complicated the design and which problems were solved this way).

[chiphogg]

I've written some docs internally that explain the idea of a "magnitude", and what problem it solves. Let me check whether I need permission to share them, as that would give us a real head start on the doc updates!

[chiphogg]

I have added the magnitude doc, which is an adaptation of an internal doc from Aurora. It's not intended to be complete, in part because my conan isn't currently working (see #384). I also didn't know how the LaTeX math (in $$) would translate to the mp-units docs---I didn't see any other examples of this.

Regardless, I hope this new commit constitutes "the part that's hard for other people". :grin: It's easier to edit than to write. LMK how you think we should proceed from here!

[chiphogg]

I sat down to try my hand at making the updates, but I can't seem to figure out how to get the docs to build. I think the problem is that UNITS_BUILD_DOCS is OFF, and I don't know how to toggle it to ON for a single run of conan build, and googling didn't seem to help. Sorry for such a basic question, but, is it possible to configure the documented config options on the fly for individual runs?

[mpusz]

You can find the instructions here: https://mpusz.github.io/units/usage.html#building-documentation. Please let me know in case it does not work.

If you prefer conan build rather than using cmake then it should work nicely with something like that:

pip3 install -r docs/requirements.txt
conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -c user.build:all=True
conan build .

but the above will compile all of the sources as well so it will take longer to complete.

[chiphogg]

You can find the instructions here: https://mpusz.github.io/units/usage.html#building-documentation. Please let me know in case it does not work.

If you prefer conan build rather than using cmake then it should work nicely with something like that:

pip3 install -r docs/requirements.txt
conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -c user.build:all=True
conan build .

but the above will compile all of the sources as well so it will take longer to complete.

Sorry to keep failing at something so basic. I know how to write C++, but I'm realizing how spoiled I am by our dedicated devtools team and bazel installation at work! :grimacing: Consequently, when I step out into the "real world", I find I have very dim understanding of tools like conan and cmake which are quite common outside my bubble.

I had already tried the build-the-docs instructions, and they didn't work. In reading more of the doc page, I think it's because my cmake is version 3.22, which is earlier than the 3.23 which the "preset" feature requires?

Anyway: I blew away my conan install (by deleting the files named at the bottom of .gitignore), then reinstalled via your instructions above; no success. I even tried with the installation command from the doc page, but replacing True with False for skip_docs; no success.

In case it helps give a clue, I still see -- UNITS_BUILD_DOCS: OFF in my output from conan build ..

[JohelEGP]

Do you want to see the built documentation? Perhaps they can be uploaded as artifacts from the CI.

[chiphogg]

I just want to be able to build the docs locally, so I can iterate on the doc build errors with a reasonable turnaround time.

[mpusz]

@chiphogg, I must say it is really strange. You do not have to blow away any Conan files. Just conan install and conan build should do the trick independently from the CMake version you use.

When you run conan build . do you see the build of examples and unit tests and just docs are not generated? Or maybe nothing is being built at all? In such a case, please ensure that mp-units: prefix is removed from the front of the -c user.build:all=True parameter as stated here: https://github.com/mpusz/units/issues/384#issuecomment-1207257587.

Otherwise, maybe try removing the ./build directory from the repo sources before running conan install, as Conan now uses cmake_layout, which puts all of its generated files and CMake build artifacts in this hardcoded location. Maybe your previous CMake runs conflict with the build process?

In the end, you should see that a build directory was created, and the directory structure of it will depend on your CMake generator being used and Conan configuration (see the note at the end of: https://mpusz.github.io/units/usage.html#conan-quick-intro).

[mpusz]

Alternatively, do a CMake build without using presets similarly to the instructions in: https://mpusz.github.io/units/usage.html#cmake-with-presets-support.

Something like that should work:

rm -rf build
conan install . -pr <your_conan_profile> -s compiler.cppstd=20 -c user.build:all=True
cd build
cmake .. -G Ninja --toolchain generators/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build . --target documentation

[mpusz]

Please also let me know in case we can improve the project building docs so people will not struggle to build the project or its parts.

[chiphogg]

Thanks! I think it was blowing away the build/ directory that finally did it for me.

I hadn't realized I could conan install on top of a previous installation without tediously removing the files. Good to know!

I think I've addressed all the feedback so far, so it should be ready for review "for real". :slightly_smiling_face:

[chiphogg]

(Pending build results, naturally)