search

hyperledger / fabric-chaincode-node

Hyperledger Fabric Node.js Smart Contracts issues in JIRA please https://jira.hyperledger.org
https://wiki.hyperledger.org/display/fabric
Apache License 2.0
242 stars 143 forks source link

jsdocs are not getting published #422

Open denyeart opened 1 month ago

denyeart commented 1 month ago

The jsdocs are no longer getting published.

For example the source file: https://github.com/hyperledger/fabric-chaincode-node/blob/main/docs/_jsdoc/tutorials/using-contractinterface.md

Should get pushed to gh-pages branch here: https://github.com/hyperledger/fabric-chaincode-node/blob/gh-pages/main/api/tutorial-using-contractinterface.html

Which then gets rendered here: https://hyperledger.github.io/fabric-chaincode-node/main/api/tutorial-using-contractinterface.html

Look at the "fabric-contract-api" version in the above pages, you'll see the first link references 2.5.0 while the latter links still reference the outdated 2.4.1.

It looks like the jsdocs used to get published in the Azure Pipelines job at: https://github.com/hyperledger/fabric-chaincode-node/blob/main/ci/azure-pipelines.yml#L218-L283

However, when Azure Pipelines was replaced by GitHub Actions, it looks like the jsdoc job did not get migrated over.

@mbwhite @bestbeforetoday I assume we should still be publishing the jsdocs as part of the GitHub Actions? What trigger would be appropriate?

Also, I'm a little confused because the tutorial https://github.com/hyperledger/fabric-chaincode-node/blob/main/TUTORIAL.md looks like a copy paste of https://github.com/hyperledger/fabric-chaincode-node/blob/main/docs/_jsdoc/tutorials/using-contractinterface.md. Should one of them be removed?

denyeart commented 1 month ago

It looks like the same issue exists for fabric-chaincode-java, here's the old javadoc publish: https://github.com/hyperledger/fabric-chaincode-java/blob/main/ci/azure-pipelines.yml#L123-L161

bestbeforetoday commented 1 month ago

Definitely the docs should get published by GitHub Actions workflows. I would expect them to be published in the push.yaml workflow. The azure-pipelines.yml is probably the reference for the exact mechanism used. The (pre-mkdocs) publishing workflow from the fabric-gateway repository (push.yml, git_push_changes.sh) might also be a useful reference for how to implement in GitHub Actions.

mbwhite commented 1 month ago

+1 TO @bestbeforetoday comments;

deleted my previous comment - mis read this was Nodejs... pre coffee brain just went to javadoc.

bestbeforetoday commented 1 month ago

As a (better) alternative to the approach I linked above that pushes a new commit to the gh-pages branch and lets GitHub's branch publishing do its thing, the latest publishing approach used by fabric-gateway publishes content directly to GitHub Pages (using standard GitHub Actions), avoiding the need for a docs branch, security holes to allow unreviewed pushes, or git wizardry.

https://github.com/hyperledger/fabric-gateway/blob/b1408ecece87c575b9d0a912385510c85107e32f/.github/workflows/push.yml#L12-L50

It's based on the GitHub documentation here.