[documentation] #3878: Add the documentation-related Iroha configurat…

[6r1d]

Original issue: #3878

We're actively using the "Code snippets" feature, and I'm trying to have more.
While doing hyperledger-iroha/iroha-2-docs#394, I want to reach some granularity.

I can either have Cargo.toml for the "Client setup" section of the Rust tutorial here or add it to the snippets directory in Iroha 2 documentation. It has less chance of remaining unnoticed for a long time if it belongs to the main repo, at least in my opinion.

Collecting a list of doc-related configurations that depend on the release in the main repo seems OK to me, but someone may disagree.

Please comment here.

[0x009922]

Let me try to understand better what is the problem we need to solve.

To clarify the context, the documentation piece is the following:

Once the initial v2.0.0 release is complete, we plan to create a package on crates.io with all the documentation. In the meantime, you could use the local copy that you've just created in the previous step as a local installation in your client's Cargo.toml:

[dependencies]
iroha_client = { version = "=2.0.0-pre-rc.13", path = "~/Git/iroha/client" }
iroha_data_model = { version = "=2.0.0-pre-rc.13", path = "~/Git/iroha/data_model" }
iroha_crypto = { version = "=2.0.0-pre-rc.13", path = "~/Git/iroha/crypto" }
iroha_config = { version = "=2.0.0-pre-rc.13", path = "~/Git/iroha/config" }

You say:

It has less chance of remaining unnoticed for a long time if it belongs to the main repo, at least in my opinion.

So the problem is that this snippet (and other similar ones) might get outdated, right?

This doesn't make much sense for me. First of all, I have a strong confusion about versioning, releases, v2.0.0, rc.13, and path = ~/Git/iroha/crypto. It is so overcomplicated for the tutorial guide to mention all of this. IMO, the approach of the tutorial must be as straightforward as possible. It is hardly achievable now, because we have stable, dev and lts channels all with different APIs and guarantees about backwards and forwards compatibility.

What should the documentation rely on???

IMO, it should rely on something single.

Coming back to the original issue. IMO, there is no need to integrate documentation-related Cargo.tomls into the main Iroha repository. A one that is integrated into the repo will look like this:

[dependencies]
iroha_client.workspace = true
# or
iroha_client = { path = "../../client" }

And this doesn't make any sense for the documentation. If we want to achieve a "real-world"-like Iroha-based project configuration, we might create a real-world Iroha-based project and store it as a separate repo, e.g. hyperledger/iroha-2-docs-rust-tutorial-source. In that project, you can define a working Cargo.toml, as close as possible to the project users might create. (Actually, users might clone that repo and run everything step-by-step, make changes in code, etc).

[dependencies]
iroha_client = { "git" = "https://github.com/hyperledger/iroha.git", branch = "iroha2-stable" }

This is how you can use Iroha at the moment, in reality. Shall we create such a project? Might be a good idea. We will have a truly working independent sample. Now we have mostly ephemeral snippets of code, integrated into the main repo with crutches.

Also, I want to make another point. IMHO, things like describing a Cargo.toml for a working project should not be possible to outdate that easy. If it happens, it means Iroha API is not yet stable enough to be documented on the level of "beginner user tutorial".

In conclusion, I think we need to very clearly identify the versioning of Iroha 2, the guarantees and boundaries. The documentation needs a single, clear, and stable target to document.

[coveralls]

Pull Request Test Coverage Report for Build 6390060375

• 0 of 0 changed or added relevant lines in 0 files are covered.
• 6274 unchanged lines in 108 files lost coverage.
• Overall coverage decreased (-0.8%) to 58.644%

---

Files with Coverage Reduction	New Missed Lines	%
cli/src/main.rs	1	0.0%
cli/src/samples.rs	1	0.0%
cli/src/torii/pagination.rs	1	98.9%
config/base/src/runtime_upgrades.rs	1	51.72%
config/src/torii.rs	1	96.67%
core/src/smartcontracts/isi/block.rs	1	87.5%
crypto/src/merkle.rs	1	96.23%
data_model/src/domain.rs	1	48.25%
logger/src/lib.rs	1	95.15%
config/src/lib.rs	2	0.0%

Totals
Change from base Build 5423219773:	-0.8%
Covered Lines:	21697
Relevant Lines:	36998

---

💛 - Coveralls

[0x009922]

@6r1d, same as with #3870 - closing this in favor of the examples repo?