build2 integration doc update

[Klaim]

This PR adds a more complete description of how to use the build2's package of nlhomann-json to consume the library in build2 projects.

Note that build2 is not only a package-manager but also a build-system and both tools are designed to work together, this impacts the verbosity of this documentation. I might have been too detailed or beginner-friendly in some parts, feel free to point if I should shortcut some of the explanations. In doubt, for the case of exising build2 projects, I opted to use the "detail/summary" markdown/html tags so that people who already know about these steps (experimented build2 users) dont have to read the whole paragraph. The details are for less experimented build2 users.

The provided source files do not constitute as provided a valide build2 project, that involves a specific organisation in particular for projects that use the package-manager. So instead of adding a whole project, I put there the files that will be modified from a bdep new-created project (that command creates a ready-to-work project). The example "from scratch" uses that approach.

Because build2 projects with executables usually use testscript , the executable I/O testing tooling provided by build2, I also provided a testscript for testing the output from the classic output of the example source code.

---

Pull request checklist

Read the Contribution Guidelines for detailed information.

• Changes are described in the pull request, or an existing issue is referenced.
• The test suite compiles and runs without error.
• Code coverage is 100%. Test cases can be added by editing the test suite.
• The source code is amalgamated; that is, after making changes to the sources in the include/nlohmann directory, run make amalgamate to create the single-header files single_include/nlohmann/json.hpp and single_include/nlohmann/json_fwd.hpp. The whole process is described here.

Please don't

• The C++11 support varies between different compilers and versions. Please note the list of supported compilers. Some compilers like GCC 4.7 (and earlier), Clang 3.3 (and earlier), or Microsoft Visual Studio 13.0 and earlier are known not to work due to missing or incomplete C++11 support. Please refrain from proposing changes that work around these compiler's limitations with #ifdefs or other means.
• Specifically, I am aware of compilation problems with Microsoft Visual Studio (there even is an issue label for this kind of bug). I understand that even in 2016, complete C++11 support isn't there yet. But please also understand that I do not want to drop features or uglify the code just to make Microsoft's sub-standard compiler happy. The past has shown that there are ways to express the functionality such that the code compiles with the most recent MSVC - unfortunately, this is not the main objective of the project.
• Please refrain from proposing changes that would break JSON conformance. If you propose a conformant extension of JSON to be supported by the library, please motivate this extension.
• Please do not open pull requests that address multiple issues.

[Klaim]

@nlohmann Hi! I'm not done at all with this but I would need to see the result somewhere before continuing. Does the ci makes a documentation build? I didnt find it so far.

[nlohmann]

@nlohmann Hi! I'm not done at all with this but I would need to see the result somewhere before continuing. Does the ci makes a documentation build? I didnt find it so far.

You can execute

make install_venv serve -C docs/mkdocs

and then open http://127.0.0.1:8000/

[coveralls]

coverage: 99.191%. remained the same
when pulling c0567e3 on Klaim:build2-usage
into a6a92c1 on nlohmann:develop.

[github-actions]

This pull request has been marked as stale because it has had no activity for 30 days. While we won’t close it automatically, we encourage you to update or comment if it is still relevant. Keeping pull requests active and up-to-date helps us review and merge changes more efficiently. Thank you for your contributions!

[Klaim]

Still relevant, just no time to focus on this yet. T_T I'll try this weekend but can't make any promises.

[nlohmann]

Please resolve conflicts and sign off your commits (see https://github.com/nlohmann/json/pull/4587/checks?check_run_id=35268369393).

[Klaim]

I took some time to update this but I'm having some issues:

• I can't seem to satisfy DCO, could you point me to my mistake? I did add the signature to the commits.
• The static code analysis are applied on example code, is this normal? Should I ignore it?
• My code editor removed a bunch of trailing whitespaces automatically, we can see them in the changes. Should I revert that or is this ok?

I'll try to complete this soon, I didnt try to generate the doc yet by lack of time (and no make installed on this machine) but plan to do so in the coming days.

[nlohmann]

• I can't seem to satisfy DCO, could you point me to my mistake? I did add the signature to the commits.

See https://github.com/nlohmann/json/pull/4587/checks?check_run_id=40451156048. There, a solution is described:

1. Ensure you have a local copy of your branch by checking out the pull request locally via command line.
2. In your local branch, run: git rebase HEAD~3 --signoff
3. Force push your changes to overwrite the branch: git push --force-with-lease origin build2-usage

• The static code analysis are applied on example code, is this normal? Should I ignore it?

Yes.

• My code editor removed a bunch of trailing whitespaces automatically, we can see them in the changes. Should I revert that or is this ok?

Please revert.

[Klaim]

I still have some cleanup to do, but no time left today, will continue soon. 👍🏽

[nlohmann]

I created #4801 to fix the CI. Please rebase once this is merged.

[nlohmann]

#4801 is merged. Please rebase.

[Klaim]

I still need to do a pass on the rendering, I didnt have an opportunity yet but should be able to work on it this week.

[nlohmann]

Please rebase to the latest develop branch.

[nlohmann]

Looks good to me.

[nlohmann]

LGTM. The PR is still in draft though. 🤔

[Klaim]

Sorry about that, I kept it in draft mainly because of some formatting/rendering issues I was fixing but didnt have time to focus on recently. If the current state is good (I dont have the rendering at hand to check, I'm on another machine) then great! Otherwise I'll fix the last details this weekend.