search

threshold-network / threshold

Threshold Network tooling.
https://threshold.network
GNU Affero General Public License v3.0
9 stars 7 forks source link

Update Solidity API docs #38

Closed thesis-valkyrie closed 1 year ago

thesis-valkyrie commented 1 year ago

Docs updated by workflow: https://github.com/keep-network/keep-core/actions/runs/5472175032

jMyles commented 1 year ago

Two questions:

1) It looks like you're applying a jiina-like syntax with each of these changes, but these appear to be otherwise vanilla GitBook (ie, markdown files). I guess this is because you're using the hint plugin? Don't you need to include the plugin in the config (in our case, .gitbook.yaml) for that to work? And if so, does that belong in this changeset? (Or am I missing something right in front of me? :-) ).

2) The message itself, "This file documents a code which is not yet deployed to Mainnet." is confusing - what is "a code" in this context? Did you mean to say "documents a contract"?

michalinacienciala commented 1 year ago

It looks like you're applying a jiina-like syntax with each of these changes, but these appear to be otherwise vanilla GitBook (ie, markdown files). I guess this is because you're using the hint plugin? Don't you need to include the plugin in the config (in our case, .gitbook.yaml) for that to work? And if so, does that belong in this changeset? (Or am I missing something right in front of me? :-) ).

What I wanted to achieve here is to add a warning section, similar to the one shown e.g. here. The hint syntax is documented here, I don't see any mention that using this requires plugin configuration (but I'm no expert on GitBook, maybe there's something I'm missing).

The message itself, "This file documents a code which is not yet deployed to Mainnet." is confusing - what is "a code" in this context? Did you mean to say "documents a contract"?

Yeah, good point, "This file documents a contract which is not yet deployed to Mainnet." is better, I'll update that.

Btw, I don't think merging this PR will have an immediate effect on the content displayed under docs.threshold.network, as the files modified here are not the ones that are linked in the SUMMARY.md. Initially SUMMARY.md linked to them, but GitBook made some refactoring during merge of https://app.gitbook.com/o/R2meumXNNad4y1B10iL7/s/WosjlL4zUGUMlcMfuSAp/~/diff/~/changes/227/resources/contribution and copied the files to a parent folder and changed the links. What I plan to do after the merge is to check if the copied files will be automatically updated once we change something via GitBook (although I doubt that and I may need to figure out how to better deal with the updates of the API docs).

michalinacienciala commented 1 year ago

I've updated the message. I'm going to merge this and experiment a bit with GitBook's behavior. If I notice that the hint syntax wasn't correctly recognized, I'll revert the changes.

jMyles commented 1 year ago

:+1:

I'll be curious to see whether we need to enable the plugin in the YAML config.

michalinacienciala commented 1 year ago

I'll be curious to see whether we need to enable the plugin in the YAML config.

We didn't have to enable the plugin, the formatting have worked with just using the GitBook's warning block syntax - see for example here.