Integrate go perun tutorial

[matthiasgeihs]

No description provided.

[choeppler]

The CircleCI build broke because of some invalid external links. You can also run that test with make linkcheck locally.

[ggwpez]

The CI check for the tutorial code is now missing. @matthiasgeihs

[ggwpez]

The CircleCI build broke because of some invalid external links. You can also run that test with make linkcheck locally.

Weird since the link that is reported as broken works fine. Maybe it is inserted after the page-load into the DOM.

[manoranjith]

From the CI logs, these were the broken links:

1. (go-perun/tutorial/channels/updating: line 33) broken disputes.html -

I have added a suggestion with 4 changes to fix this one.

As @ggwpez pointed out, this link is be valid but is reported as broken, probably since it is inserted after page load.

1. (go-perun/tutorial/getting-started: line 35) broken https://github.com/trufflesuite/ganache-cli#installation - Anchor 'installation' not found

[manoranjith]

Suggestions to fix broken link. Includes 4 changes.

[matthiasgeihs]

The CircleCI build broke because of some invalid external links. You can also run that test with make linkcheck locally.

From the CI logs, these were the broken links:

1. (go-perun/tutorial/channels/updating: line 33) broken disputes.html -

I have added a suggestion with 4 changes to fix this one.

As @ggwpez pointed out, this link is be valid but is reported as broken, probably since it is inserted after page load.

1. (go-perun/tutorial/getting-started: line 35) broken https://github.com/trufflesuite/ganache-cli#installation - Anchor 'installation' not found

any idea how to fix this? @manoranjith

[manoranjith]

The CircleCI build broke because of some invalid external links. You can also run that test with make linkcheck locally.

From the CI logs, these were the broken links:

1. (go-perun/tutorial/channels/updating: line 33) broken disputes.html -

I have added a suggestion with 4 changes to fix this one.

As @ggwpez pointed out, this link is be valid but is reported as broken, probably since it is inserted after page load.

1. (go-perun/tutorial/getting-started: line 35) broken https://github.com/trufflesuite/ganache-cli#installation - Anchor 'installation' not found

any idea how to fix this? @manoranjith

For the first one, have made a suggestion, for the second one I haven't found a fix yet, will have to still look for it.

In case, if we are not able to find any fix for it,y suggestion would be make linkcheck as a separate CI job and make it optional. The reviewer will then have to decide whether the Pr can be merged in cases where the job fails.

[choeppler]

In case, if we are not able to find any fix for it,y suggestion would be make linkcheck as a separate CI job and make it optional. The reviewer will then have to decide whether the Pr can be merged in cases where the job fails.

I dimly remember that there's a timeout option for the linkecheck. I think I once saw some other docs projects where that was increased. Could that be a solution for the problem?

[manoranjith]

In case, if we are not able to find any fix for it,y suggestion would be make linkcheck as a separate CI job and make it optional. The reviewer will then have to decide whether the Pr can be merged in cases where the job fails.

I dimly remember that there's a timeout option for the linkecheck. I think I once saw some other docs projects where that was increased. Could that be a solution for the problem?

I tried the timeout option with 30s. It still was reported as broken link.

Another option is to exclude check of anchors in this. In this case, the validity of link will be checked. This could be enabled by adding the following lines to the end of conf.py file. I found from sphinx docs that this option was specifically targeting cases were anchors were dynamically added to a web page.

@matthiasgeihs @choeppler

linkcheck_ignore = [
   'https://github.com/trufflesuite/ganache-cli#'
]

I couldn't make a suggestion as no lines were modified near the end of the file.

[choeppler]

@manoranjith, now that you've investigated this linkcheck problem and we have an example, could you also file a bug report with the sphinx project to maybe get the root cause solved? Thanks!

[manoranjith]

@manoranjith, now that you've investigated this linkcheck problem and we have an example, could you also file a bug report with the sphinx project to maybe get the root cause solved? Thanks!

I think this is a known limitation in linkcheck, because they have provided options exclusively to handle these scenarios where anchors in the URL are dynamically added (say by Javascript). However, I can check the existing issues in their repo to see the understand more and will create an issue if there is none covering this problem.

[matthiasgeihs]

I have addressed all comments, I think. Please have another look.

I externalized the tutorial source code into a separate repository at perun-network, where we can also gather additional code examples. The code is included here via a git submodule. I added submodule initialization to the ci and added a remark to the README.

For some reason LGTM takes ages to run since I added the submodule :(

[ggwpez]

We could also add https://github.com/perun-network/perun-tutorial as a sub-module here instead of copying the files.
But i was not involved in the planning meeting for the integration, so consider this void if it does not make sense.

[manoranjith]

@matthiasgeihs The PR LGTM now. I have 2 minor comments and a review from @choeppler on the change in conf.py:

• one is a suggestion to add (in the readme file) the steps for checking out git sub modules

• other, as a remainder to create follow up issues.

• Need review comments from @choeppler: changing authors and copyright holder name from Hyperledger to Perun Framework Contributors in conf.py.

The PR can be merged after this.

[manoranjith]

@matthiasgeihs Also could you add a one-line explanation in this commit message a09bfab, the reason for disabling autosection extension. The reason, I understand is to use manually created tags instead.

[matthiasgeihs]

We could also add https://github.com/perun-network/perun-tutorial as a sub-module here instead of copying the files.
But i was not involved in the planning meeting for the integration, so consider this void if it does not make sense.

I thought about it, but there were several changes necessary, hence I did not follow this approach.

[manoranjith]

LGTM.

The suggested changes have been accepted.