search

hyperledger / fabric-chaincode-node

Hyperledger Fabric Node.js Smart Contracts
https://hyperledger.github.io/fabric-chaincode-node/
Apache License 2.0
249 stars 144 forks source link

jsdocs are not getting published #422

Open denyeart opened 6 months ago

denyeart commented 6 months 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 6 months 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 6 months 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 6 months ago

+1 TO @bestbeforetoday comments;

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

bestbeforetoday commented 6 months 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.