doc: add instructions for generating RPC docs #20987

If I start bitcoind on regtest via bitcoind -regtest -daemon and start the generation script as described, I get:

$ go run generate.go 
2021/01/22 17:38:37 Cannot run bitcoin-cli: exit status 1, is bitcoind running?
exit status 1

Looking at the script, it doesn't seem to invoke bitcoin-cli with a specified network, therefore assuming mainnet.

Therefore either the script should be changed to really connect to regtest, or changing this to mainnet here :)

      - Run bitcoind on mainnet

I just tried and it seems to work with both mainnet and regtest, but the script itself says regtest should be specified: https://github.com/bitcoin-core/bitcoincore.org/blob/06666b83558cdd795f08969c553e722b20867cf0/contrib/doc-gen/generate.go#L5

Also, @harding said that should be regtest too, maybe he could say if that's actually needed?

Looking through the script I don't see a reason why the network should matter, although I might be missing something. But if you think I don't I could just remove this part of specifying network.

Tested on a fresh Ubuntu Focal (20.04) VM:

This worked:

sudo install git golang wget
wget https://bitcoincore.org/bin/bitcoin-core-0.21.0/bitcoin-0.21.0-x86_64-linux-gnu.tar.gz
tar -zxf bitcoin-0.21.0-x86_64-linux-gnu.tar.gz
export PATH="$PWD/bitcoin-0.21.0/bin:$PATH"
bitcoind  -noconnect -nolisten -daemon
git clone https://github.com/bitcoin-core/bitcoincore.org.git
cd bitcoincore.org/contrib/doc-gen
go run generate.go

Note:

• It will look for bitcoin-cli in the PATH, so the bin/ directory from the release needs to be added to that.
• It does not pass -regtest, so it will connect to the mainnet RPC. There seems to be no way to override this without patching the script.

Ok, so for now I have changed it to say mainnet as suggested. In the script itself, do you think it would make more sense to update the comment, or make the script use regtest? https://github.com/bitcoin-core/bitcoincore.org/blob/06666b83558cdd795f08969c553e722b20867cf0/contrib/doc-gen/generate.go#L5

I believe for the script you can specify the network in the ~/.bitcoin/bitcoin.conf file if you really need to. Only default file location works, obviously.

When I use the script, I do:

vi ~/.bitcoin/bitcoin.conf
dG  # delete everything in the file
regtest=1  # default to regtest
:w   # write the file
^Z  # suspend the editor
bitcoind -daemon
go run generate.go
bitcoin-cli stop
fg  # bring the editor back
uu  # undo edits
:wq  # write file and exit

(Yikes, writing all that out makes it sound harder than it is.) Obviously it'd be better to hardcode regtest in the generate.go script. I actually tried that once but, not knowing any go, failed at the way that seemed obvious to me and gave up immediately.

I think the reason to use regtest is that it and testnet used to have some (non-hidden) RPCs that mainnet didn't (e.g., I seem to recall that generate was removed from mainnet prior to the introduction of generatetoaddress). That's currently not the case AFAICT.

If the generated docs are really the same, I'd prefer regtest, to not waste bandwidth and hd space due to IBD starting (especially if one forgets to exit bitcoind after generation). A docker container could also be helpful here, to avoid potential conflict with another bitcoind that is already running. This way we also wouldn't need to install go or change the host machine's state in any other way. That's outside of this PR's scope though.

Thanks. So I think now it should be fine to just have it say mainnet instead as was suggested here?

f the generated docs are really the same, I'd prefer regtest, to not waste bandwidth and hd space due to IBD starting

I agree. This is why I pass -noconnect -nolisten above, I think this prevents any IBD from starting.

Thanks. So I think now it should be fine to just have it say mainnet instead as was suggested here?

Yes, would say so. Unless the script is changed to use -regtest before this is merged, I guess. I don't personally know enough about golang to do that.

Ok, I think this PR can wait for https://github.com/bitcoin-core/bitcoincore.org/pull/751 to be merged first, then change back here to mention it should run on regtest.

I think now with https://github.com/bitcoin-core/bitcoincore.org/pull/751 merged this comment can be resolved. I've returned it to the original text here of specifying regtest.