mp-units

[mpusz]

Hi, I am the author of mp-units which is a Physical Units Library and is targeting C++23 or C++23 and uses C++20 features. Following fmtlib example I would like to use Sphinx and Breathe for the documentation. Here is an initial version: https://mpusz.github.io/units/index.html. There are still a lot of issues to resolve there. Among others #479, #480, #481, #482.

Also, I am using a VSCode which by the default provides a space in a kit name (i.e. GCC 9.2.1 which results in a space in a build path). For this case, the #478 issue was submitted.

I suck at Python ;-) but I will do my best to help resolve above and other issues remaining. If you could help me it would be great too. You can find all of the source docs in my repo. I will be adding more code references when the initial problems are solved.

[mpusz]

Hi again, the documentation of my project was updated recently. You can find it here: https://mpusz.github.io/units. Right now It is probably the biggest documentation using Breathe so you might consider referring to it on your website :-)

It is also probably the first big project using C++20 and with this, a lot of issues happen. You can find a lot of them in the "Reference" section of my documentation. Also, there are many errors reported during the CI build. Some of them are not C++20 specific and apply to previous C++ versions as well. It would be great if you could find some time to help me clean them up and make this documentation a showcase of Breathe features :-)

[mpusz]

Another update to the docs done. This time I have a major issue as the Travis CI does not want to finish the build because of the number of warnings and errors reported by Sphinx and Breathe: https://travis-ci.com/github/mpusz/units/builds/184157816. Also, I had to disable some documentation pages as they crash the documentation generation process (https://github.com/mpusz/units/tree/master/docs_disabled).

I would appreciate every help with cleaning this up.

[vermeeren]

@mpusz A workaround could be to write a wrapper script around the CI scripts that filters out Warning: Duplicate target detected: using grep or similar. Not a a proper fix but at least avoids build failure.

[mpusz]

When I added -Q for Sphinx I was able to fit in the logfile limit ;-) It does not mean that the problems are fixed though...

[mpusz]

I moved the CI to GitHub Actions which allowed me to enable all of the warnings again. You can find it here: https://github.com/mpusz/units/runs/1357942287?check_suite_focus=true#step:10:10. I would really appreciate it if we could start working on fixing those together.

[vermeeren]

@mpusz A starting point would be to analyse the error log and determine the cause for each type of error. Then open up feature request or report bug on the project in question (probably either Breathe or Sphinx's C/C++ domain). For example all things Invalid C++ declaration I think is missing support for some C++ feature on Sphinx's side. See https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/domains/cpp.py. As usual fastest way to get things done is to submit patches, developer time is scarce.

The duplicate target warning is common, searching for this on the Breathe issue tracker reveals quite some issues. Newest one #594. So far bad usage, where the user creates duplicate definitions, is the main cause of this. But with new C++ there is a chance it triggers with correct usage too.

[utzig]

I had never used conan before but when I run conan install ... I get:

ERROR: Failed requirement 'linear_algebra/0.7.0@public-conan/stable' from 'conanfile.py (mp-units/0.7.0)'
ERROR: Unable to find 'linear_algebra/0.7.0@public-conan/stable' in remotes

Where does this package come from?

[mpusz]

A few of example applications require linear_algebra package. The whole instruction to compile the code is here: https://mpusz.github.io/units/usage.html#contributing-or-just-building-all-the-tests-examples-and-documentation. TL'DR, just do the following:

conan remote add linear-algebra https://api.bintray.com/conan/twonington/public-conan
git clone https://github.com/mpusz/units.git && cd units
pip3 install -r docs/requirements.txt
mkdir build && cd build
conan install .. -pr <your_conan_profile> -s compiler.cppstd=20 -e mp-units:CONAN_RUN_TESTS=True -b outdated -u
conan build ..

In case of problems with a Conan profile the following might help: https://mpusz.github.io/units/usage.html#conan-quick-intro.