added instructions for viewing docs locally#9194
added instructions for viewing docs locally#9194TabError wants to merge 1 commit intorclone:masterfrom
Conversation
After editing the source code and adding new commands or flags the documentation needs to be built again. Therefore rclone needs to be built from the source code. Then one needs to run `rclone gendocs`. But there is also a make target 'commanddocs' which automates this but wasn't documented anywhere.
| go generate ./lib/transform | ||
| -@rmdir -p '$$HOME/.config/rclone' | ||
| XDG_CACHE_HOME="" XDG_CONFIG_HOME="" HOME="\$$HOME" USER="\$$USER" rclone gendocs --config=/notfound docs/content/ | ||
| XDG_CACHE_HOME="" XDG_CONFIG_HOME="" HOME="\$$HOME" USER="\$$USER" ./rclone gendocs --config=/notfound docs/content/ |
There was a problem hiding this comment.
I'll let @ncw weigh in on this, as I think it was intentional to rely on GOPATH. That said, it has definitely tripped me up before. There's probably some improvement (even if not this one) that would be worth making to make things easier for new developers.
There was a problem hiding this comment.
In our Makefile is there any use of rclone that is bound to the build from the source code itself?
Most targets involving rclone are uploads of the docs or for (beta) releases. So in these cases it is irrelevant which version rclone has. In lines 235 and 237 it explicitly calls the local version too:
Line 235 in 7d0a8bf
| ## Changes on commands | ||
|
|
||
| If you have worked on the commands in `cmd/*` and you want to see the | ||
| changed docs locally, you can run `make commanddocs serve` to | ||
| regenerate the command docs and serve the website locally. | ||
|
|
There was a problem hiding this comment.
Thanks.
I'm thinking, maybe this should be moved to the CONTRIBUTING.md instead? There is a quite detailed section about writing documentation, but it focuses mostly on backend docs. Command docs is mentioned towards the end of that section, but it could use some mentioning of the make commanddocs / rclone gendocs part.
Maybe a link from here and into the CONTRIBUTING.md would be relevant.
After editing the source code and adding new commands or flags the documentation needs to be built again. Therefore rclone needs to be built from the source code. Then one needs to run
rclone gendocs. But there is also a make target 'commanddocs' which automates this but wasn't documented anywhere.What is the purpose of this change?
I am a new contributor and while working on another PR i had a hard time figuring out why my local version of the docs didn't show up correctly.
Checklist