🎉 Pterry and roxygen2

Fix #59

content/post/2023-10-21-sir-pterry-was-a-master-of-words/index.md

@@ -0,0 +1,36 @@
+---
+title: Sir Pterry Was a Master of Words
+author: Roel M. Hogervorst
+date: '2023-10-21'
+slug: sir-pterry-was-a-master-of-words
+categories:
+  - blog
+tags:
+  - 100DaysToOffload
+  - DiscWorld
+subtitle: 'Quotes from "Interesting Times"'
+difficulty:
+  - beginner
+post-type:
+  - post
+
+---
+I'm slowly going through some highlights I made in 2017 ( I discovered the 
+text file of highlights exported from my old kindle ebook reader a few weeks
+back in my archive). I love the watch series more than anything from the discworld
+books, but the Rincewind series has amazing quotes too. Here are some highlights
+from 'Interesting Times'
+
+> *People are always a little confused about this, as they are in the case of miracles. When someone is saved from certain death by a strange concatenation of circumstances, they say that’s a miracle. But of course if someone is killed by a freak chain of events—the oil spilled just there, the safety fence broken just there—that must also be a miracle. Just because it’s not nice doesn’t mean it’s not miraculous. p 316 Interesting Times
+
+(beautiful description of change and how we percieve it)
+
+
+> Once again a foot kicked Rincewind in the kidneys, making its usual explicit request in the Esperanto of brutality. p 148 Interesting Times
+
+You could have said universal language, but this is so much better!
+
+
+*I’m publishing this as part of 100 Days To Offload. You can join in yourself by visiting https://100daystooffload.com, post - 29/100*
+
+*Find other posts tagged  [#100DaysToOffload here](https://notes.rmhogervorst.nl/tags/100DaysToOffload/)*

content/post/2023-10-22-sir-pterry-was-a-master-of-words/index.md

@@ -0,0 +1,44 @@
+---
+title: Sir Pterry Was a Master of Words, part 2
+author: Roel M. Hogervorst
+date: '2023-10-22'
+slug: sir-pterry-was-a-master-of-words
+categories:
+  - blog
+tags:
+  - 100DaysToOffload
+  - DiscWorld
+subtitle: 'Quotes from Eric'
+difficulty:
+  - beginner
+post-type:
+  - post
+---
+
+I'm slowly going through some highlights I made in 2017 ( I discovered the 
+text file of highlights exported from my old kindle ebook reader a few weeks
+back in my archive). I love the watch series more than anything from the discworld
+books, but the Rincewind series has amazing quotes too. Here are some highlights
+from Eric (Rincewind # 4)
+
+
+> It is well known that eight colors make up white. But there are also eight colors of blackness, for those that have the seeing of them, and the hives of Death are among the black grass in the black orchard under the black-blossomed, ancient boughs of trees that will, eventually, produce apples that…put it like this…probably won’t be red. --p2 
+
+(the buildup, it is just lovely!
+Interestingly there are black apples among the 5000 cultivars of apples that we 
+have today!)
+
+
+> Interestingly enough, the gods of the Disc have never bothered much about judging the souls of the dead, and so people only go to hell if that’s where they believe, in their deepest heart, that they deserve to go. Which they won’t do if they don’t know about it. This explains why it is important to shoot missionaries on sight. p125
+
+
+> The Tezuman Empire in the jungle valleys of central Klatch is known for its organic market gardens, its exquisite craftsmanship in obsidian, feathers and jade, and its mass human sacrifices in honor of Quezovercoatl, the Feathered Boa, god of mass human sacrifices. As they said, you always knew where you stood with Quezovercoatl. It was generally with a lot of people on top of a great stepped pyramid with someone in an elegant feathered headdress chipping an exquisite obsidian knife for your very own personal use. The Tezumen are renowned on the continent for being the most suicidally gloomy, irritable and pessimistic people you could ever hope to meet, for reasons that may soon be made clear. It was true about the time measurement as well. The Tezumen had realized long ago that everything was steadily getting worse and, having a terrible literal-mindedness, had developed a complex system to keep track of how much worse each succeeding day was. p34
+
+This is just a beautiful mix of everything we know about the Aztec people.
+Just look at that beautiful bastardization of 'Quetzalcoatl' to 'Quezovercoatl'!
+
+
+
+*I’m publishing this as part of 100 Days To Offload. You can join in yourself by visiting https://100daystooffload.com, post - 30/100*
+
+*Find other posts tagged  [#100DaysToOffload here](https://notes.rmhogervorst.nl/tags/100DaysToOffload/)*

content/post/2023-10-23-docs-not-showing-with-roxygen2-check-the-entire-file/index.md

@@ -0,0 +1,80 @@
+---
+title: Docs not Showing with Roxygen2? Check the Entire File
+author: Roel M. Hogervorst
+date: '2023-10-23'
+slug: docs-not-showing-with-roxygen2-check-the-entire-file
+categories:
+  - R
+tags:
+  - TIL
+  - 100DaysToOffload
+subtitle: ''
+difficulty:
+  - intermediate
+post-type:
+  - lessons-learned
+---
+Recently I had a weird experience with roxygen2. I wanted to create docs for a
+piece of code but they were just not showing up!
+
+For some context; I'm the maintainer of the ropensci [{charlatan}](https://github.com/ropensci/charlatan) package that fakes data. 
+I am currently working on a major rewrite that will make it much easier to add new
+features. Roxygen2 is a package that helps you write documentation. One of its
+best features is that you write the docs in the same file as the code, that 
+prevents it from going out of date. 
+Roxygen is specific for R, but in python you can export docstrings and use
+redoc or sphinx to build docs for your software too (there must also be 
+jave versions and for other languages too, but I don't write in those languages).
+
+
+What was the problem?
+
+This is what the top of the file looked like:
+
+```r
+#' @title PersonProvider
+#' @details Methods for Persons, methods for generating names.
+#' @inherit BaseProvider note
+#' @family ParentProviders
+#' @export
+#' @returns A PersonProvider object that can create names. 
+PersonProvider <- R6::R6Class(
+	...
+```
+If you have worked with roxygen you will notice
+- `@export` tag: so that means export this file in the package
+- `@title` and `@details` (not necessary but I like this to be explicit)
+
+This all suggests that the docs should be exported, but they were not.
+
+I finally opened an issue on roxygen and got a fast reply.
+I shot myself in the foot again.
+
+
+Somewhere in this file I had a `@noRd` tag:
+
+```r
+...
+    #' @description messy switch (internal).
+    #' Always return a text, when messy is allowed return a messy
+    #' version, but otherwise return a clean version.
+    #' @noRd
+    #' @param clean_choice the clean version
+    #' @param messy_choice the messy version
+    messy_switch = function(clean_choice, messy_choice) {
+    ...
+```
+
+And that tag is valid for the whole manual file. 
+
+So search for `@noRd` when your file does not render!
+
+
+Gabor also responded with some more details that I had read, but forgot:
+
+> roxygen2 parses the #' comments until the end of the function (or object) definition. This can be quite handy when you want to keep the a piece of the manual page close to the code it documents. E.g. this is an example I like: [r-lib/cli@d888311/R/num-ansi-colors.R#L37](https://github.com/r-lib/cli/blob/d8883112a8060c1f011cccc9147dd35db03bb9c6/R/num-ansi-colors.R#L37)
+
+
+*I’m publishing this as part of 100 Days To Offload. You can join in yourself by visiting https://100daystooffload.com, post - 31/100*
+
+*Find other posts tagged  [#100DaysToOffload here](https://notes.rmhogervorst.nl/tags/100DaysToOffload/)*