✨feature: add doc #1986

jasonandjay · 2023-09-29T09:29:29Z

Add bitcoinjs-lib documentation

Automatically read ts file and generate
Automatically triggered by github actions (github pages need to be enabled)

package.json

junderw · 2023-09-29T17:33:05Z

TODO:

Figure out why deploy-doc is broken.
Add more comments to various items in the library so that the docs are more fleshed out.

jasonandjay · 2023-09-30T00:16:57Z

TODO:

Figure out why deploy-doc is broken.

Add more comments to various items in the library so that the docs are more fleshed out.

I guess it may caused by get pages token failed.
You can enable github pages first and select source from github actions, then you can re-run failed job.

junderw · 2023-09-30T01:05:02Z

Still not working.

This is the yaml file it recommended me when I tried to configure a static HTML setup through Github Actions.

Perhaps something is missing from your diff? Could you look into it for me?

# Simple workflow for deploying static content to GitHub Pages
name: Deploy static content to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["master"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  # Single deploy job since we're just deploying
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          # Upload entire repository
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

junderw · 2023-09-30T01:08:03Z

Looks like actions/configure-pages is missing?

jasonandjay · 2023-09-30T01:39:48Z

Looks like actions/configure-pages is missing?

logger report [Branch "doc" is not allowed to deploy to github-pages due to environment protection rules.]
To allow the "doc" branch to deploy to GitHub Pages, you'll need to adjust the branch protection rules. Follow these steps:

Go to your GitHub Repository:
Open the repository in your browser.

Click on "Settings":
It's usually located near the right end of the menu bar, next to "Actions" and "Insights".

Navigate to "Branches":
In the left sidebar, click on the "Branches" tab.

Select "Add rule":
You should see an option to add a new branch protection rule. Click on it.

Enter "doc" as the branch name:
In the "Branch name pattern" field, type "doc" to specify the branch you want to adjust the rules for.

Configure Protection Rules:
Here, you'll have several options. You'll want to pay attention to the following:

Require pull request reviews before merging: If you have this enabled, make sure it allows merging without approval. You might need to disable it temporarily for the "doc" branch.

Require status checks to pass before merging: Ensure that the necessary checks (e.g., GitHub Pages deployment) are not required for the "doc" branch.

Include administrators: Make sure this option is checked if you want administrators to be exempt from these rules.

Save Changes:
After making the necessary adjustments, click on the "Save changes" button.

junderw · 2023-09-30T15:59:38Z

Ok, well, I can verify the results of the doc command locally. Perhaps we should make the doc jobs only run on master.

Having it run on pull requests will just pollute the CI with failed tests.

jasonandjay · 2023-10-02T18:23:27Z

Deploy doc task has updated, it will only take effect on master branch.

junderw · 2023-10-02T20:04:24Z

I wonder about versioning.

If it would be possible to have it recognize whether it's being deployed on master or a tag and change the URL path?

Then maybe people could navigate to older versions by clicking a link to the docs generated for a specific tag.

I would hope that the default page is the last tagged version or something.

If that's not possible, I guess it's fine.

I'd also like to flesh out some of the documentation in this PR so that the first release of the docs isn't so bare bones.

If you can help by documenting any of the smaller stuff I'd appreciate it. The more the better.

jasonandjay · 2023-10-05T06:41:22Z

I think add version control is possible and necessary but with low priority.
And flesh out documentation is how priority.
I want to add description and examples to function、class、interface and namespace.
examples can be copied from tests, so users can easy to use and it`s better for us to maintain.

such as fromBase58Check, do you think any other content or content style do we need to add?

jasonandjay · 2023-10-05T06:58:54Z

For properties, we can add description like this, do you think its ok?

junderw · 2023-10-05T07:07:06Z

I want to add description and examples to function、class、interface and namespace. examples can be copied from tests, so users can easy to use and it`s better for us to maintain.

such as fromBase58Check, do you think any other content or content style do we need to add?

This looks fine. I am a little worried about tests and their copy-pasted doc-equivalents going stale... but I think as long as I remember to mention fixing the doc strings in review it should be fine.

I think add version control is possible and necessary but with low priority.

Yeah, this is a "nice to have"

You are awesome, thanks for your help!

junderw · 2023-11-02T07:21:05Z

package.json

@@ -54,6 +54,7 @@
    "bech32": "^2.0.0",
    "bip174": "^2.1.1",
    "bs58check": "^3.0.1",
+    "typedoc-plugin-bitcoinjs-runcase": "^1.0.1",


Shouldn't this be a devDependency?

Yes, it should me. I remember this but maybe something is wrong!!

I want to tell you about another thing.
I added an executable environment to the document to help us more flexibly display related cases and provide user testing.
The background is as follows

We have a lot of test cases. Moving too many cases will affect the organizational structure of our code, and the workload will be huge.

For related cases, single testing can be combined with the context to understand more, more comprehensively and more efficiently.

To achieve this goal, I did the following things, which also cost me a lot of time:

Build bitcoinjs-lib browser version

Develop typedoc-plugin-bitcoinjs-runcase plug-in to support sneaking into the executable environment

Modify relevant comment tags

You can view the relevant effects here: https://jasonandjay.github.io/bitcoinjs-lib/functions/address.fromBase58Check.html

I think this is a great feature, but I need your help evaluating whether it's suitable

That way we can tell the user to test here and find more cases in the single test

Then we only need to give a correct usage method in example (I customized a @case tag), so that the construction efficiency of our document will be much higher

@junderw please take a look

@jasonandjay typedoc-plugin-bitcoinjs-runcase is a production dependency and has react and react-dom as dependencies. That doesn't belong in bitcoinjs at all.

@pajasevi yes, i will change it later, i want to know is this the right direction to add an executable environment to the document to simplify the case in the single test? so as to proceed with the next step.

This will take a while to review.

Perhaps this should be in a follow up pr

Review typedoc plugin or comments in our repository?

Adding typedoc-plugin-bitcoinjs-runcase should be in a separate PR is what I'm saying.

jasonandjay · 2023-11-05T02:47:52Z

Got it
typedoc-plugin-bitcoinjs-runcase is a devDependencies, so it will not intrude into our program and help provide a run code environment when building documents.

It will now be more efficient for us to improve the documentation

Or, let’s add the key comments in the document first, and then add the run case. What do you think?

Muniru0

Amazing work.

…to doc

jasonandjay · 2024-02-29T18:06:33Z

I did two things

⏪ rollback: separate typedoc-plugin-bitcoinjs-runcase to another PR
Add key comments to the code to make the document look more complete.

junderw · 2024-03-01T01:01:25Z

Thanks. That lowers the scope of the review significantly. I'll take another look later today.

jasonandjay · 2024-03-06T10:29:06Z

Is there anything that needs to be optimized? Maybe we can push document construction to next step.

junderw

LGTM. Great job. Github is being weird. Crossing finger that this works lol.

junderw · 2024-03-06T10:58:33Z

Deployed successfully!

https://bitcoinjs.github.io/bitcoinjs-lib/

Maybe add this to the README?

✨feature: add doc

5b8f4fc

junderw reviewed Sep 29, 2023

View reviewed changes

package.json Outdated Show resolved Hide resolved

junderw reviewed Sep 29, 2023

View reviewed changes

package.json Outdated Show resolved Hide resolved

🐞 fix: update package.json

bc0ef13

jasonandjay had a problem deploying to github-pages September 29, 2023 17:28 — with GitHub Actions Failure

jasonandjay had a problem deploying to github-pages September 30, 2023 00:31 — with GitHub Actions Failure

jasonandjay had a problem deploying to github-pages September 30, 2023 00:32 — with GitHub Actions Failure

✨feature: update deploy-doc ci only trigger on master branch

b76e645

jasonandjay added 4 commits October 5, 2023 18:26

📄 docs: comment address namespace

5382260

📄 docs: build src after comment address namespace

6463bbc

✨feature: add custom tag @case to create a runnable environment

caea960

🐞 fix: build src

19b31eb

junderw reviewed Nov 2, 2023

View reviewed changes

🐞 fix: move typedoc-plugin-bitcoinjs-runcase to devDependencies

f5995bd

junderw mentioned this pull request Feb 27, 2024

A Comprehensive Documentation for BitcoinJs-Lib. #2048

Closed

Muniru0 approved these changes Feb 29, 2024

View reviewed changes

⏪ rollback: separate typedoc-plugin-bitcoinjs-runcase to another PR

4a1913e

jasonandjay added 7 commits March 1, 2024 01:48

⏪ rollback: remove runcase of address module

5bf4367

📄 docs: add docs for payments module

6cc676d

📄 docs: add docs fro script namespace

94039ae

📄 docs: add other docs and build src

3dc81f7

Merge branch 'bitcoinjs:master' into doc

5655cd4

Merge branch 'doc' of https://github.com/jasonandjay/bitcoinjs-lib in…

c6cb2f8

…to doc

🐞 fix: fix romat:ci

4ef1bdc

junderw approved these changes Mar 6, 2024

View reviewed changes

junderw merged commit 894ad02 into bitcoinjs:master Mar 6, 2024
12 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

✨feature: add doc #1986

✨feature: add doc #1986

jasonandjay commented Sep 29, 2023

junderw commented Sep 29, 2023

jasonandjay commented Sep 30, 2023

junderw commented Sep 30, 2023

junderw commented Sep 30, 2023

jasonandjay commented Sep 30, 2023

junderw commented Sep 30, 2023

jasonandjay commented Oct 2, 2023

junderw commented Oct 2, 2023

jasonandjay commented Oct 5, 2023

jasonandjay commented Oct 5, 2023

junderw commented Oct 5, 2023

junderw Nov 2, 2023

jasonandjay Nov 2, 2023

jasonandjay Nov 2, 2023

jasonandjay Nov 3, 2023

pajasevi Nov 3, 2023

jasonandjay Nov 3, 2023

junderw Nov 3, 2023

junderw Nov 3, 2023

jasonandjay Nov 5, 2023

junderw Nov 5, 2023

jasonandjay commented Nov 5, 2023

Muniru0 left a comment

jasonandjay commented Feb 29, 2024

junderw commented Mar 1, 2024

jasonandjay commented Mar 6, 2024

junderw left a comment

junderw commented Mar 6, 2024

✨feature: add doc #1986

✨feature: add doc #1986

Conversation

jasonandjay commented Sep 29, 2023

junderw commented Sep 29, 2023

jasonandjay commented Sep 30, 2023

junderw commented Sep 30, 2023

junderw commented Sep 30, 2023

jasonandjay commented Sep 30, 2023

junderw commented Sep 30, 2023

jasonandjay commented Oct 2, 2023

junderw commented Oct 2, 2023

jasonandjay commented Oct 5, 2023

jasonandjay commented Oct 5, 2023

junderw commented Oct 5, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jasonandjay commented Nov 5, 2023

Muniru0 left a comment

Choose a reason for hiding this comment

jasonandjay commented Feb 29, 2024

junderw commented Mar 1, 2024

jasonandjay commented Mar 6, 2024

junderw left a comment

Choose a reason for hiding this comment

junderw commented Mar 6, 2024