docs/r_markdown_docs/README.md

   1 ## SGN Documentation
   2 [View the documentation](http://solgenomics.github.io/sgn/)
   3
   4 ### Syntax and Use
   5
   6 This folder `docs/` can be used to build the site through R package - bookdown. More about bookdown here.
   7
   8 https://bookdown.org/
   9 https://bookdown.org/yihui/bookdown/
  10
  11 The entire page along with the source files in r-markdown format are in the folder
  12 `/docs/r_markdown_docs`
  13
  14 ### Tools.
  15 The best way to work with the documentation is to
  16 1. Install the free R Studio with on your local machine with the sgn repository.
  17 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()`.
  18 3. Install R package “bookdown”, "rmarkdown" and "pandoc".
  19
  20 ###   How to work with documentation
  21 1. **Introduction**
  22 This section provides an overview of managing R Markdown documentation using Bookdown and outlines the purpose of this technical manual.
  23 2. **Defining the Document Structure** in `_bookdown.yml` file.
  24 Files: Structure of the document is stored in `_bookdown.yml` file.
  25 `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.
  26 Setting the Order of Chapters/Sections: Order of chapters is an order of files in `Rmd_files` list.
  27 3. **Adding New Chapters/Sections**
  28 Creating New R Markdown Files: to create a new sectiono or chapter - just create a `<filename>.Rmd` file in `/docs/r_markdown_docs` folder.
  29 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.
  30 4. **Building Your Documentation**
  31 Rendering the Documentation: Best way to render document is to use knit icon ( command ) in `RStudio` when open `Index.Rmd`
  32 Alternative to preview html gitbook format and pdf is to use command in R:
  33 `bookdown::render_book("index.Rmd", "bookdown::pdf_book")`
  34 `bookdown::render_book("index.Rmd", "bookdown::gitbook")`
  35 Previewing the Documentation: Best option is RStudio - with `knit` command we have also a live local server for gitbook html documents.
  36 5. **Deployment and Sharing**
  37 Publishing Your Documentation:
  38     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.
  39     2. Build and check in `RStudio` or any other live server if changes are correct and documentation looks correct.
  40     3. Commit changes to sgn repository and create a new pull request. With the new pool github through github action will check if there are any changes in `r_markdown_docs` folder and if yes, will trigger a gitaction to automatically build documentation on github containers.
  41     4. If build action will pass, then when the branch with documation changes is merged with master, Gitaction workflow automatically builds proper gitbook html document, and pdf, and then deploy static version of html to github pages.
  42     That process is completely automated.
  43
  44     * Build and check locally in RStudio
  45     * Commit changes in `r_markdown_docs` folder and create pull request
  46     * Check if the GitHub Action test for building documentation passes.
  47     * Merge to master and check GitHub Action workflow result.
  48
  49
  50 For markdown Gitbook syntax
  51 https://bookdown.org/yihui/rmarkdown/markdown-syntax.html
  52
  53 # Basic syntax.
  54
  55 ### Emphasis
  56
  57 *italic*   **bold**
  58
  59 _italic_   __bold__
  60
  61 ### Headers
  62
  63 # Header 1
  64 ## Header 2
  65 ### Header 3
  66
  67 ### Lists
  68
  69 Unordered List:
  70 * Item 1
  71 * Item 2
  72     + Item 2a
  73     + Item 2b
  74
  75 Ordered List:
  76 1. Item 1
  77 2. Item 2
  78 3. Item 3
  79     + Item 3a
  80     + Item 3b
  81
  82 ### R Code Chunks
  83 R code will be evaluated and printed
  84
  85 ```{r}
  86 summary(cars$dist)
  87 summary(cars$speed)
  88 ```
  89
  90 ### Inline R Code
  91 There were `r nrow(cars)` cars studied
  92
  93 ### Links
  94 Use a plain http address or add a link to a phrase:
  95
  96 http://example.com
  97
  98 [linked phrase](http://example.com)
  99
 100 ### Images
 101 Images on the web or local files in the same directory:
 102
 103 ![](http://example.com/logo.png)
 104
 105 ![optional caption text](figures/img.png)
 106
 107 ### Blockquotes
 108 A friend once said:
 109
 110 > It's always better to give
 111 > than to receive.
 112
 113 ### Plain Code Blocks
 114 Plain code blocks are displayed in a fixed-width font but not evaulated
 115
 116 ```
 117 This text is displayed verbatim / preformatted
 118 ```
 119 ### Inline Code
 120
 121 We defined the `add` function to compute the sum of two numbers.
 122
 123 Inline equation:
 124 $equation$
 125
 126 Display equation:
 127
 128 $$ equation $$
 129
 130 ### Horizontal Rule / Page Break
 131 Three or more asterisks or dashes:
 132
 133 ******
 134
 135 ------
 136 Tables
 137 First Header  | Second Header
 138 ------------- | -------------
 139 Content Cell  | Content Cell
 140 Content Cell  | Content Cell
 141 Reference Style Links and Images
 142
 143 ### Links
 144 A [linked phrase][id].
 145 At the bottom of the document:
 146
 147 [id]: http://example.com/ "Title"
 148
 149 ### Images
 150 ![alt text][id]
 151 At the bottom of the document:
 152 [id]: figures/img.png "Title"
 153
 154 ### Manual Line Breaks
 155 End a line with two or more spaces:
 156
 157 Roses are red,
 158 Violets are blue.
 159
 160 ### Miscellaneous
 161 superscript^2^
 162 ~~strikethrough~~