When I followed the instructions to run the training repo on my PC, I encountered an error that was resolved by making changes to the Makefile.
previous code :
error :
After code :
I added the double quotes in the path variables to SPHINXBUILD AND SPHINXAUTOBUILD.
Should I go ahead and raise the pull request, or is this error something others have also encountered?
You can try manually entering the parts of the command in a terminal session, substituting values for the variables, to see exactly why it fails at line 44.
There is a space character in your realpath. Try creating the project where its path has no space characters, and try again to see if that resolves the issue.
I am somewhat surprised that no one has hit this issue in over two years after modernizing these Makefiles, but I guess most seasoned developers have already been bitten by, and learned from, the rule of "don't use special characters in file paths and names".
Nonetheless, all documentation follows that pattern, so if you do end up submitting a pull request, you should do it for both repositories. I think it makes sense to wrap variables that may have spaces or other special characters with double quote marks so that they are expanded correctly.
Finally, please do not submit images of text, but use URLs and actually text. See Why should I not upload images of code/data/errors? - Meta Stack Overflow.
Thanks, @stevepiercy I'll give it a manual go and explore all possibilities to gain a deeper understanding of this error. If I encounter any issues, I'll report back to you. Your suggestion is greatly appreciated. Moving forward, I'll avoid using code images directly. Thanks for the insightful tip—I wouldn't have known otherwise!
Hey @stevepiercy,
This whitespace-related issue is affecting both the volto repo and the training repo:
cd ./docs/ && /home/veenu/Desktop/Gsoc org/Documentation/training/bin/sphinx-build -b html -d ../_build/doctrees . ../_build/html
/bin/sh: 1: /home/veenu/Desktop/Gsoc: not found
make: *** [Makefile:44: html] Error 127
I'm facing the same problem with volto repo as well, and I found the root cause of the issue.. More details are available in this forum post:
I'm planning to make changes in this part of the Makefile:
SPHINXBUILD = "$(realpath bin/sphinx-build)"
SPHINXAUTOBUILD = "$(realpath bin/sphinx-autobuild)"
This modification should help resolve the whitespace-related issue. I'd appreciate your thoughts on this approach!
let me know if you need any more changes!
This is fine, but would you please try the test I suggested in my previous comment:
If you can create a project that way, then that confirms my theory. Thank you!
Hey @stevepiercy, your theory is correct. This time I've created three folders named Work , work new and work-new .
Let's talk about the /work new folder 
:
As expected, it gives me an error:
cd ./docs/ && /home/veenu/Desktop/work new/training/bin/sphinx-build -b html -d ../_build/doctrees . ../_build/html
/bin/sh: 1: /home/veenu/Desktop/work: not found
make: *** [Makefile:44: html] Error 127
Now, the /Work folder 
:
make html works perfectly.
generating indices... genindex done
writing additional pages... search done
copying images... [100%] workflow/_static/simple_workflow.png
dumping search index in English (code: en)... done
dumping object inventory... done
sphinx-sitemap: sitemap.xml was generated for URL https://training.plone.org/ in /home/veenu/Desktop/Work/training/_build/html/sitemap.xml
build succeeded, 460 warnings.
The HTML pages are in ../_build/html.
Build finished. The HTML pages are in ../_build/html.
And lastly /work-new folder :
generating indices... genindex done
writing additional pages... search done
copying images... [100%] workflow/_static/simple_workflow.png
dumping search index in English (code: en)... done
dumping object inventory... done
sphinx-sitemap: sitemap.xml was generated for URL https://training.plone.org/ in /home/veenu/Desktop/work_new/training/_build/html/sitemap.xml
build succeeded, 463 warnings.
The HTML pages are in ../_build/html.
Build finished. The HTML pages are in ../_build/html.
This indicates that the make html command works perfectly in the /Work and /work-new folder, but there's an issue in the /work new folder due to a path error.
Excellent! Would you please go ahead and submit pull requests to the following repositories that build documentation and need these two Makefile variables to be wrapped in double-quotes?
realpath is used:
For Volto, Plone REST API and plone.api, you will need to sign the Plone Contributor Agreement if you have not yet done so.
Following your guidance, I've submitted two pull requests for Documentation and Training docs. I took the liberty to contact the relevant authorities yesterday to initiate the update process for my Plone Contributor Agreement. In the meantime, I've added a note for merging the pull request, referring to the commit message outlined in the training docs. I appreciate your support, and I'll patiently await my new Plone agreement before creating pull requests for Volto, Plone REST API, and plone.api.
Hey, got a quick question for you. What do you think about this idea: I'm thinking of drafting pull requests for Volto, Plone REST API, and plone.api. Once I've got my new Plone Agreement sorted, I'll go ahead and finalize those pull requests. What's your take on this? Appreciate your thoughts!
Hey @stevepiercy,
I've looked into the linkcheckbroken issue. The problem is affecting the make test run for my recent pull request in the Documentation repository. As a result, the MakeFile test is not passing.
I'm wondering whether it's advisable to wait for GitHub to address this issue before attempting the test again. Alternatively, do you recommend a different approach to address this challenge?
Error I am facing:
( backend/widgets: line 414) broken https://github.com/zopefoundation/z3c.form/tree/master/src/z3c/form/browser - HTTPSConnectionPool(host='github.com', port=443): Read timed out. (read timeout=5)
make: *** [Makefile:192: linkcheckbroken] Error 1
Error: Process completed with exit code 2.
I merged the Training PR, but you closed the Documentation PR.
Thank you for following that procedure.
It's fine to draft pull requests locally, and even push them to your remote branch, but wait for your approved Plone Contributor Agreement and being added to the Plone Contributors Team. Thank you for asking.
The following is not directed toward you, but to all newcomers who do not follow guidelines. When newcomers do not wait to be added to the Plone Contributors Team and prematurely open a pull request, that wastes everyone's time and irritates core developers. In fact I and @ichimdav and I will bring up this issue at the next Volto Team meeting for discussion. The large number of newcomers who barge in without following guidelines has become a severe drain on core developer time. They could be working productively, instead of managing irrelevant comments and pull requests. We might immediately close and lock such issues and pull requests with a comment to follow our guidance. This might go against Plone's openness policy, but we also expect contributors to seek out, respect, and follow guidelines with minimal direction.
Please search the documentation issue tracker for linkcheckbroken.
Noticing test errors, I accidentally shared the Pull Request link before confirming results. Realizing the failed tests, I promptly canceled that pull request, fearing my code caused the failures. After running the code locally, I discovered the test failures were due to other issues, specifically related to linkcheckbroken as found in your GitHub issues. Subsequently, I created a new pull request for the same issues.
Are you suggesting me to address this GitHub Linkcheckbroken issue? Yesterday, I researched the problem on Google but found no solutions. I also personally checked the links, and strangely, they took much time to open. In the link-check-broken issue, the suggestion is to replace the links with raw README files.
Can I proceed with this approach? Any guidance would be helpful.
From the referenced issue:
linkcheckbroken currently fails due to a recent change in GitHub. It is a regression that they should fix.
...
There is an open discussion in GitHub Community.
...
This issue is merely a placeholder until GitHub can deploy a fix.