Docs: Update instructions for publishing site #2998
Conversation
| mkdocs gh-deploy | ||
| rm -r site | ||
| mkdir site | ||
| cp ../.asf.yaml site/ |
There was a problem hiding this comment.
As this uses ../.asf.yaml, which directory does this document assume we are running these commands from?
There was a problem hiding this comment.
Good point. I updated the README to include this information.
There was a problem hiding this comment.
If we're in the $projectRoot/site directory, should it be rm -r docs && mkdir docs?
My site directory looks as follows.
$ ls -la site
total 24
drwxr-xr-x 6 kbendickson staff 192B Aug 19 16:08 .
drwxr-xr-x 59 kbendickson staff 1.8K Aug 19 16:08 ..
-rw-r--r-- 1 kbendickson staff 1.6K Aug 19 16:08 README.md
drwxr-xr-x 43 kbendickson staff 1.3K Aug 20 00:48 docs
-rw-r--r-- 1 kbendickson staff 3.5K Aug 19 16:08 mkdocs.yml
-rw-r--r-- 1 kbendickson staff 872B Aug 19 16:08 requirements.txt
If I enter the site directory, and rm -r site, I get an exception.
$ cd site
$ rm -r site
rm: site: No such file or directory
There was a problem hiding this comment.
I am a bit confused, why is site removed and recreated in this process?
There was a problem hiding this comment.
@jackye1995, normally the site directory is removed and built entirely from the docs directory when gh-deploy runs. Removing the site directory, copying the file by hand, and using --dirty does basically the same thing, but allows us to end up with .asf.yaml in the output that gets copied to the asf-site branch. That's required for publishing now, which is why this change is needed.
| ### Publishing | ||
|
|
||
| After site changes are committed, you can publish the site with this command: | ||
| After site changes are committed, you can publish them by running the following sequence of commands from the `$projectRoot/site` directory: |
There was a problem hiding this comment.
I think $projectRoot makes this more confusing than necessary. I think this should just refer to the site directory. If you want to make it more clear than that, then state that it's the directory where this README.md is located:
... sequence of commands from the
sitedirectory (where thisREADME.mdis located):
| cp ../.asf.yaml site/ | ||
| mkdocs gh-deploy --dirty | ||
| ``` | ||
| This assumes that the Apache remote is named `apache` and will push to the `asf-site` branch. To use a different remote add `-r <remote-name>` to the `mkdocs` command. |
There was a problem hiding this comment.
Please add a blank line to separate the preformatted content from the next paragraph, like before.
|
@cwsteinbach, can you please add a description to this PR? |
|
Closing this PR in favor of #3008. |
4 participants
Update instructions for publishing site.