How do we use pkgdown to build a website

[gregorgorjanc]

Laura how do you use pkgdown to build the website? Please write the procedure here so me and @janaobsteter understand it and maybe automate it. ALSO, we need to ensure that the build does not overwrite or delete the CNAME file in it

https://github.com/HighlanderLab/SIMplyBee/blob/main/docs/CNAME

This file is added by GitHub when we setup the webpages thingy bla bla

[LStrachan]

The vignettes probably explain it a lot better than me but I'll give it a shot.

1. Run once to configure your package to use pkgdown usethis::use_pkgdown()

2. If you run pkgdown::build_site() it'll create all the folders and files that you need (docs/man/README/ the yml file) and make a shell of a site

3. You edit the site using the yml file, everything else is automatic. I basically mimicked our yml file from the slendr yml file. The main amount of work it changing and adding in all the function references, every function must be present in the yml file or it will throw an error.

4. Once you save the yml file you can run 'pkgdown::build_site()' again. It will use the yml file as a template and rewrite or update all of the other files. Using this function re-builds everything, there are others like build_articles() that only target certain parts of the site.

I'm not sure if build_site() would remove the CNAME file. That's something I'll have to google.

I'm still deciphering how to update the site with their vignette (https://pkgdown.r-lib.org/articles/how-to-update-released-site.html). It might be as simple as having development mode on to AUTO but I'll have a look around

[LStrachan]

An updated documents for HOW-TO-MAKE-A-PKGDOWN-SITE (which auto-updates)

# 1. Install and download the pkgdown package 
install.packages("pkgdown")
library(pkgdown)

# 2. Set working directory to the github repository you'd like 
setwd("Github repository")

# 3. Run this usethis:: ONCE to configure your package to use pkgdown.
# use_pkgdown(): creates a simple pkgdown config file (_pkgdown.yml) and adds relevant files or directories to .Rbuildignore and .gitignore.
usethis::use_pkgdown()

# 4. Use build_site() to build the website 
# Your README.md becomes the homepage, documentation in man/ generates a function reference, 
# and vignettes will be rendered into articles/. 
# You need a vignettes file with .Rmd vignettes for this to convert properly 
pkgdown::build_site()

# Errors may occur here but don't panic!!!
# pkgdown usually has very clear error messages to fix things quickly

# If reference/functions errors are occuring make sure you've installed the package with all the functions on (you might need your developing version)
# If it carries on, open your _pkgdown.yml file (which should now be partially written) and remove/add the fuctions manually

# Also if there is an error you don't have to rerun build_site everytime or it'll take ages!
pkgdown::build_articles()   # creates the vignette articles. REMEMBER that pkgdown can only use images in 'man/figures' and 'vignettes' 
pkgdown::build_home()       # builds homepage 
pkgdown::build_reference()  # builds reference section
pkgdown::build_favicon()    # creates icons for your logos 
pkgdown::build_news()       # creates news section
# there are other but these are the basics

# If everything has ran nicely and you've tackled any errors then WELL DONE you have a basic website!!!!
# Now lets customise it a bit 
#build_site automatically runs the _pkgdown.yml file so any alterations are done in that file 

# you _pkgdown.yml file will contain only at this point 
url: ~
  template:
  bootstrap: 5

#Things you can add to the yml file 
title : PACKAGE NAME 
url : THE HTTP LINK TO YOUR PURCHASED DOMAIN #you need to also link from the url end 

delevopment:
  mode : auto #this make the site automatically update with your GitHub

#Control the navigations bar (This is an example of simplybee.info set-up)
navbar:
  structure:
  left: [home, reference, articles, news]
  right: [github]
components:
  home:
    icon: fa-home
    href: index.html
  reference:
    icon: fa-question-circle
    text: Reference
    href: reference/index.html
  articles:
    icon: fa-book
    text: Articles
    menu:
     - text: Honeybee Biology                 #Title of the article (you can change this)
       href: articles/A_Honeybee_biology.html # Link to the article (you can't change the link name)
     - text: Colony Events
       href: articles/C_Colony_events.html
     - text: Multiple colonies
       href: articles/B_Multiple_colonies.html
     - text: Crossing
       href: articles/D_Crossing.html
     - text: Genomics
       href: articles/E_Genomics.html
     - text: Sampling functions
       href: articles/G_Sampling_functions.html
     - text: Quantitative Genetics
       href: articles/F_Quantitative_Genetics.html
     - text: FAQs
       href: articles/Z_FAQs.html

# You can also organise your functions/references in categories 
# This examples is from simplybee.info 
       # UNFORTUNATELY YES THE TABS and SPACES DO MATTER 
# You can't miss out ANY functions in this section or it will throw an error
 reference:
   - title: Class
     contents:
     - Colony-class
     - MultiColony-class
     - SimParamBee
     - c,NULLOrPop-method

  - title: Colony and MultiColony operations
  - subtitle: Utility
     contents:
     - createColony
     - setLocation
     - createMultiColony
     - selectColonies
     - pullColonies
     - removeColonies
     - getId

  - title: Caste operations
  - subtitle: Create
    desc: (output is Population) # You can add a description to the sections 
    contents:
    - createWorkers
    - createDrones
    - createVirginQueens
    - createDCA

# There are other customisation avaiable such as homepage colours etc but check the pkgdown vignettes for more information https://pkgdown.r-lib.org/index.html

#After your site is all made, let's make it autoupdate! 
# This will create a _pkgdown.yaml file (DON'T CONFUSE IT WITH YOUR yml FILE) to initiate the auto-update workflow
# WARNING: MAKE SURE YOU DON'T OVERWRITE YOUR yml FILE!!! or you'll have to start writing it again 
pkgdown::build_site_github_pages()  

# The yaml file is autowritten: but if it is not look at the SIMplyBee repository for an example version 
#This should now all work with github actions when you commit something new to your main branch (NOT your devel) 
# If an error occurs, your GitHub Actions will fail and flag an error about where the problem is (it's luckly pretty clear)

#WELL DONE!!! A FULLY FUNCTIONING WEBSITE!!

#This is how your workflow is going to look 
1. Write some code
2. Push and merge that code to your main branch 
3. This will trigger your workflows
4. The pkgdown.yaml workflow will trigger:
        - pkgdown::build_site() 
        - an update of all of your pkgdown files
        - trigger github pages which will launch your site (not host it unless you specify that)
        - automatically update your site 

MAJOR NOTE!!!!!
IF YOU ARE CHANGING THE README.MD FILE IT MIGHT NOT UPDATE THE SITE'S HOMEPAGE
THIS ISN'T CURRENTLY WORKING IN THE WORKFLOW
SO COPY THE CONTENTS OF THE README.MD FILE AND PUT IT INTO THE DOCS/INDEX.HTML FILE AND IT WILL UPDATE THE SITE 

# THE END :)