Updating documentation website

The documentation website (https://docs.quanteda.io) should be built from the latest version of quanteda on CRAN, to avoid confusion caused by different function specifications between the CRAN and Github versions. To ensure this, we separated the website to the gh_pages branch, which should only be rebuilt between updating CRAN and accepting new pull requests.

Building a website is simply to run pkgdown::build_site(). Once the website has been built, make a commit and push files in /docs to the gh-pages branch. This can be done by git subtree push --prefix docs origin gh-pages.

Workflows

Updating website is easy but note that website will be inaccessible between step 4 to shortly after step 5 (downtime will be around 5 min)

Full-update

1. Make sure that you are on the CRAN version by commit IDs
2. Build website by pkgdown::build_site()
3. Stage all the files in /docs and make a commit
4. Delete the old website branch by git push origin --delete gh-pages
5. Push files to website branch by git subtree push --prefix docs origin gh-pages
6. Check if the version number in the reference is the same as the latest CRAN version
7. Done

Partial-update

1. Checkout the latest CRAN version by git checkout -b [branch name] [commit ID] as a separate branch. Branch name can be anything but should be like CRAN-v1.0.0; commit IDs are available in the release page
2. On the new branch, extract files that you want to update from the master by git checkout --patch master [file1] [file2]. Files are, for example, R/corpus-methods-base.R and R/corpus_segment.R
3. Build website by pkgdown::build_site() or reference by pkgdown::build_reference()
4. Stage all the files in /docs and make a commit
5. Delete the old website branch by git push origin --delete gh-pages
6. Push files to website branch by git subtree push --prefix docs origin gh-pages
7. Check if the version number in the reference is the same as the latest CRAN version
8. Done

Search function

This is a new feature of pkgdown website that utilizes DocSearch. Currently only the Github version of pkgdown supports DocSearch. According the developer, we can customize:

• Look and feel (https://community.algolia.com/docsearch/documentation/)
• Indexing (https://github.com/algolia/docsearch-configs/blob/master/configs/quanteda.json)

Since indexing is done by the DocSearch crawler every 24 hours, we need to request changes in settings through a pull request. pkgdown's website also uses this the service and its setting file is also on in the folder.