Rmarkdown / gitbook format manual all documents

[darekbienkowski]

Description

SGN Documentation

View the documentation

Syntax and Use

This folder docs/ can be used to build the site through R package - bookdown. More about bookdown here.

https://bookdown.org/
https://bookdown.org/yihui/bookdown/

The entire page along with the source files in r-markdown format are in the folder
/docs/r_markdown_docs

Tools.

The best way to work with the documentation is to

1. Install the free R Studio with on your local machine with the sgn repository.
2. Set the working directory environment variable to the path from our documentation R command setwd("{path_on_local_machine}/sgn/docs/r_markdown_docs") we can check current working directory by getwd().
3. Install R packages “bookdown”, "rmarkdown", "pandoc", and "knitr". Load each using library() (e.g. library(bookdown)).

How to work with documentation

1. Introduction
   This section provides an overview of managing R Markdown documentation using Bookdown and outlines the purpose of this technical manual.

2. Defining the Document Structure in _bookdown.yml file.
   Files: Structure of the document is stored in _bookdown.yml file.
   rmd_files variable in _bookdown.yml is a list of documents used to build a documentation in a given order. If we want to add a new file to documentation - it must be added to the Rmd_files list and a new file must be created in r_markdown_docs folder with .Rmd extension.
   Setting the Order of Chapters/Sections: Order of chapters is an order of files in rmd_files list.

3. Adding New Chapters/Sections
   Creating New R Markdown Files: to create a new section or chapter - just create a <filename>.Rmd file in /docs/r_markdown_docs folder.
   Updating the Rmd Files List: Once you create a file and want to add it to official documentation update _bookdown.yml -> rmd_files with new additions.

4. Building Your Documentation
   Rendering the Documentation: Best way to render document is to open index.Rmd in RStudio and use the knit icon ( command ).
   Alternatively, to preview html gitbook format and pdf use the R command:
   bookdown::render_book("index.Rmd", "bookdown::pdf_book")
bookdown::render_book("index.Rmd", "bookdown::gitbook")
   Previewing the Documentation: Best option is RStudio - with knit command we have also a live local server for gitbook html documents.

5. Deployment and Sharing
   Publishing Your Documentation:

   1. Once changes in documentation are done. Please save all .Rmd files in the r_markdown_docs folder and check _bookdown.yml file if the structure is correct.
   2. Build and check in RStudio or any other live server if changes are correct and documentation looks correct.
   3. Commit changes to sgn repository and create a new pull request. With the new pull github through github action will check if there are any changes in r_markdown_docs folder. If there are, it will trigger a gitaction to automatically build documentation on github containers.
   4. If build action passes, then when the branch with documentation changes is merged with master, Gitaction workflow automatically builds proper gitbook html document, and pdf, and then deploys a static version of html to github pages.
      That process is completely automated.
   • Build and check locally in RStudio
   • Commit changes in r_markdown_docs folder and create pull request
   • Check if the GitHub Action test for building documentation passes.
   • Merge to master and check GitHub Action workflow result.

Checklist

• Refactoring only
• Documentation only
• Fixture update only
• Bug fix
  • The relevant issue has been closed.
  • Further work is required.
• New feature
  • Relevant tests have been created and run.
  • Data was added to the fixture
    • Data was added via a patch in /t/data/fixture/patches/.
  • User-Facing Change
    • The user manual in /docs has been updated.
  • Any new Perl has been documented using perldoc.
  • Any new JavaScript has been documented using JSDoc.
  • Any new legacy JavaScript has been moved from /js to /js/source/legacy.

[alockrow]

I couldn't get bookdown::render_book("index.Rmd", "bookdown::pdf_book") to work (some sort of LaTeX error) but everything else looks good!