Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: core-geth features, generated API method docs #306

Merged
merged 13 commits into from
Feb 4, 2021

Conversation

meowsbits
Copy link
Member

@meowsbits meowsbits commented Jan 18, 2021

Working on adding some documentation about what makes core-geth core-geth.

Resolves #308

@meowsbits
Copy link
Member Author

@meowsbits
Copy link
Member Author

I'm gonna squash this and mark ready for review.

- Creates generated markdown docs for API methods
  ./docs/JSON-RPC-API/modules
- 'make docs-generate' (re)creates these files
- ./docs/core/index.md is added including some hopefully
  useful information about what makes core-geth core-geth

Date: 2021-01-15 06:43:58-06:00
Signed-off-by: meows <[email protected]>
@meowsbits meowsbits changed the title WIP: docs for core-geth features docs: core-geth features, generated API method docs Jan 21, 2021
@meowsbits
Copy link
Member Author

meowsbits commented Jan 21, 2021

Aside from the generated API method docs (./docs/JSON-RPC-API/modules/*.md), here's the most significant content addition: https://github.com/etclabscore/core-geth/blob/docs/core-geth-features/docs/core/index.md.

tree for reference:

> tree docs
docs
├── audits
│   ├── 2017-04-25_Geth-audit_Truesec.pdf
│   ├── 2018-09-14_Clef-audit_NCC.pdf
│   ├── 2019-10-15_Discv5_audit_LeastAuthority.pdf
│   └── 2020-01-24_DiscV5_audit_Cure53.pdf
├── core
│   ├── alltools.md
│   ├── evmc.md
│   └── index.md
├── developers
│   ├── build-from-source.md
│   ├── create-new-release.md
│   ├── documentation.md
│   └── versioning.md
├── getting-started
│   ├── installation.md
│   └── run-cli.md
├── img
│   └── favicon.png
├── index.md
├── JSON-RPC-API
│   ├── index.md
│   ├── modules
│   │   ├── admin.md
│   │   ├── debug.md
│   │   ├── ethash.md
│   │   ├── eth.md
│   │   ├── miner.md
│   │   ├── net.md
│   │   ├── personal.md
│   │   ├── trace.md
│   │   ├── txpool.md
│   │   └── web3.md
│   └── openrpc.md
└── tutorials
    └── private-network.md

8 directories, 28 files

@meowsbits meowsbits marked this pull request as ready for review January 21, 2021 19:53
meowsbits and others added 5 commits January 21, 2021 14:04
- also fixup the accidentally-removed workaround
for the cited open-rpc/meta-schema issue; see changes
in node/node.go

Date: 2021-01-21 14:04:37-06:00
Signed-off-by: meows <[email protected]>
This allows more precise deep (anchor) linking.

Fixes the extra css which remove the too-much-information
ul's from the right secondary nav.

Date: 2021-01-21 17:37:47-06:00
Signed-off-by: meows <[email protected]>
Didn't work for me, but what do I know.

Date: 2021-01-21 19:15:34-06:00
Signed-off-by: meows <[email protected]>
@meowsbits
Copy link
Member Author

meowsbits commented Jan 22, 2021

Just putting this out there... the generated docs in docs/JSON-RPC-APIs/modules/ aren't deterministic. And this bothers me. It's going to be practically impossible to review diffs, for example. The nondeterminism is caused, I believe exclusively, by Go's non-guaranteed map ordering.

…ion examples

Date: 2021-01-22 08:53:47-06:00
Signed-off-by: meows <[email protected]>
Date: 2021-01-22 08:56:05-06:00
Signed-off-by: meows <[email protected]>
This reverts commit 048f515.

Turns out didn't work for him either.
@ziogaschr
Copy link
Member

Would be nice if they can be deterministic, though I can leave with that as this PR brings a lot of value in the docs.

@meowsbits
Copy link
Member Author

meowsbits commented Jan 23, 2021

cc5afb0 begins the ordering solve. In fact, so far, it seems to be 100% effective. I don't think its a complete solution because the template also includes information (as Raw JSON) from the plain old json.MarshalIndent which shouldn't guarantee ordering, but at least for me, for now, that doesn't seem to be an issue. Note this commit's diff with de73918, showing that only the generated-at timestamps and expected lines are modified.

Would be nice if they can be deterministic, though I can leave with that as this PR brings a lot of value in the docs.
#306 (comment)

With these last two commits, I'm happy merging this and following up later if the json.MarshalIndent causes undesirable noise. For now, close enough.

Date: 2021-01-23 05:00:37-06:00
Signed-off-by: meows <[email protected]>
@meowsbits
Copy link
Member Author

meowsbits commented Feb 3, 2021

@ziogaschr PTAL #306 (comment). I'm OK with merging if you are.

@ziogaschr
Copy link
Member

Looks fine for me at the moment. Nice work man. We can do a new PR when and if needed.

@meowsbits meowsbits merged commit 6dd9074 into master Feb 4, 2021
@meowsbits meowsbits deleted the docs/core-geth-features branch February 4, 2021 13:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

docs: add OpenRPC service discovery document markdown
2 participants