Leonard... the reason roxygen exists is to allow markup in source files to be used to automatically generate the numerous files required by standard R packages as documented in Writing R Extensions. If your goal is to not use source files this way then the solution is to not use roxygen at all. Just create those files yourself by directly editing them from scratch. On September 3, 2023 7:06:09 PM PDT, Leonard Mada via R-help <r-help at r-project.org> wrote:>Thank you Bert. > > >Clarification: > >Indeed, I am using an add-on package: it is customary for that package - >that is what I have seen - to have the entire documentation included as >comments in the R src files. (But maybe I am wrong.) > > >I will try to find some time over the next few days to explore in more >detail the R documentation. Although, I do not know how this will >interact with the add-on package. > > >Sincerely, > > >Leonard > > >On 9/4/2023 4:58 AM, Bert Gunter wrote: >> 1. R-package-devel is where queries about package protocols should go. >> >> 2. But... >> "Is there a succinct, but sufficiently informative description of >> documentation tools?" >> "Writing R Extensions" (shipped with R) is *the* reference for R >> documentation. Whether it's sufficiently "succinct" for you, I cannot >> say. >> >> "I find that including the documentation in the source files is very >> distracting." >> ?? R documentation (.Rd) files are separate from source (.R) files. >> Inline documentation in source files is an "add-on" capability >> provided by optional packages if one prefers to do this. Such packages >> parse the source files to extract the documentation into the .Rd >> files/ So not sure what you mean here. Apologies if I have misunderstood. >> >> " I would prefer to have only basic comments in the source >> files and an expanded documentation in a separate location." >> If I understand you correctly, this is exactly what the R package >> process specifies. Again, see the "Writing R Extensions" manual for >> details. >> >> Also, if you wish to have your package on CRAN, it requires that the >> package documents all functions in the package as specified by the >> "Writing ..." manual. >> >> Again, further questions and elaboration should go to the >> R-package-devel list, although I think the manual is really the >> authoritative resource to follow. >> >> Cheers, >> Bert >> >> >> >> On Sun, Sep 3, 2023 at 5:06?PM Leonard Mada via R-help >> <r-help at r-project.org> wrote: >> >> Dear R-List Members, >> >> I am looking for collaborators to further develop the BioShapes >> almost-package. I added a brief description below. >> >> A.) BioShapes (Almost-) Package >> >> The aim of the BioShapes quasi-package is to facilitate the >> generation >> of graphical objects resembling biological and chemical entities, >> enabling the construction of diagrams based on these objects. It >> currently includes functions to generate diagrams depicting viral >> particles, liposomes, double helix / DNA strands, various cell types >> (like neurons, brush-border cells and duct cells), Ig-domains, as >> well >> as more basic shapes. >> >> It should offer researchers in the field of biological and chemical >> sciences a tool to easily generate diagrams depicting the studied >> biological processes. >> >> The package lacks a proper documentation and is not yet released on >> CRAN. However, it is available on GitHub: >> https://github.com/discoleo/BioShapes >> >> Although there are 27 unique cloners on GitHub, I am still looking >> for >> contributors and collaborators. I would appreciate any >> collaborations to >> develop it further. I can be contacted both by email and on GitHub. >> >> >> B.) Documentation Tools >> >> Is there a succinct, but sufficiently informative description of >> documentation tools? >> I find that including the documentation in the source files is very >> distracting. I would prefer to have only basic comments in the source >> files and an expanded documentation in a separate location. >> >> This question may be more appropriate for the R-package-devel list. I >> can move the 2nd question to that list. >> >> ### >> >> As the biological sciences are very vast, I would be very happy for >> collaborators on the development of this package. Examples with >> existing >> shapes are available in (but are unfortunately not documented): >> >> Man/examples/Examples.Man.R >> R/Examples.R >> R/Examples.Cells.R >> tests/experimental/* >> >> >> Many thanks, >> >> Leonard >> >> ______________________________________________ >> R-help at r-project.org mailing list -- To UNSUBSCRIBE and more, see >> https://stat.ethz.ch/mailman/listinfo/r-help >> PLEASE do read the posting guide >> http://www.R-project.org/posting-guide.html >> <http://www.R-project.org/posting-guide.html> >> and provide commented, minimal, self-contained, reproducible code. >> > [[alternative HTML version deleted]] > >______________________________________________ >R-help at r-project.org mailing list -- To UNSUBSCRIBE and more, see >https://stat.ethz.ch/mailman/listinfo/r-help >PLEASE do read the posting guide http://www.R-project.org/posting-guide.html >and provide commented, minimal, self-contained, reproducible code.-- Sent from my phone. Please excuse my brevity.
On 03/09/2023 10:47 p.m., Jeff Newmiller wrote:> Leonard... the reason roxygen exists is to allow markup in source files to be used to automatically generate the numerous files required by standard R packages as documented in Writing R Extensions. > > If your goal is to not use source files this way then the solution is to not use roxygen at all. Just create those files yourself by directly editing them from scratch.Just a bit of elaboration on Jeff's suggestion -- here's the workflow I prefer to using Roxygen. Once you have a function that works: 1. install the package 2. set your working directory to the package "man" directory 3. run `prompt(functionname)` 4. edit `functionname.Rd` in the "man" directory, which will already be filled in as a skeleton help file, with comments describing what else to add. Don't run prompt() again after editing, or you'll lose all your edits. But this is a good way to get started. I think for the first few times the comments are really helpful, but I wouldn't mind a way to suppress them. Duncan Murdoch
>>>>> Jeff Newmiller >>>>> on Sun, 03 Sep 2023 19:47:32 -0700 writes:> Leonard... the reason roxygen exists is to allow markup in > source files to be used to automatically generate the > numerous files required by standard R packages as > documented in Writing R Extensions. If your goal is to > not use source files this way then the solution is to not > use roxygen at all. Just create those files yourself by > directly editing them from scratch. Yes. Many experienced R programmers do not use Roxygen (or use it only rarely; e.g., together with ESS (Emacs Speaks Statistics) to make the initial creation or sometime a thorough updating the help pages man/*.Rd more convenient). There are different tastes and different work flows for different people. Martin > On September 3, 2023 7:06:09 PM PDT, Leonard Mada via > R-help <r-help at r-project.org> wrote: >> Thank you Bert. >> >> >> Clarification: >> >> Indeed, I am using an add-on package: it is customary for >> that package - that is what I have seen - to have the >> entire documentation included as comments in the R src >> files. (But maybe I am wrong.) >> >> >> I will try to find some time over the next few days to >> explore in more detail the R documentation. Although, I >> do not know how this will interact with the add-on >> package. >> >> >> Sincerely, >> >> >> Leonard >> >> >> On 9/4/2023 4:58 AM, Bert Gunter wrote: >>> 1. R-package-devel is where queries about package >>> protocols should go. >>> >>> 2. But... "Is there a succinct, but sufficiently >>> informative description of documentation tools?" >>> "Writing R Extensions" (shipped with R) is *the* >>> reference for R documentation. Whether it's sufficiently >>> "succinct" for you, I cannot say. >>> >>> "I find that including the documentation in the source >>> files is very distracting." ?? R documentation (.Rd) >>> files are separate from source (.R) files. Inline >>> documentation in source files is an "add-on" capability >>> provided by optional packages if one prefers to do >>> this. Such packages parse the source files to extract >>> the documentation into the .Rd files/ So not sure what >>> you mean here. Apologies if I have misunderstood. >>> >>> " I would prefer to have only basic comments in the >>> source files and an expanded documentation in a separate >>> location." If I understand you correctly, this is >>> exactly what the R package process specifies. Again, see >>> the "Writing R Extensions" manual for details. >>> >>> Also, if you wish to have your package on CRAN, it >>> requires that the package documents all functions in the >>> package as specified by the "Writing ..." manual. >>> >>> Again, further questions and elaboration should go to >>> the R-package-devel list, although I think the manual is >>> really the authoritative resource to follow. >>> >>> Cheers, Bert >>> >>> >>> >>> On Sun, Sep 3, 2023 at 5:06?PM Leonard Mada via R-help >>> <r-help at r-project.org> wrote: >>> >>> Dear R-List Members, >>> >>> I am looking for collaborators to further develop the >>> BioShapes almost-package. I added a brief description >>> below. >>> >>> A.) BioShapes (Almost-) Package >>> >>> The aim of the BioShapes quasi-package is to facilitate >>> the generation of graphical objects resembling >>> biological and chemical entities, enabling the >>> construction of diagrams based on these objects. It >>> currently includes functions to generate diagrams >>> depicting viral particles, liposomes, double helix / DNA >>> strands, various cell types (like neurons, brush-border >>> cells and duct cells), Ig-domains, as well as more basic >>> shapes. >>> >>> It should offer researchers in the field of biological >>> and chemical sciences a tool to easily generate diagrams >>> depicting the studied biological processes. >>> >>> The package lacks a proper documentation and is not yet >>> released on CRAN. However, it is available on GitHub: >>> https://github.com/discoleo/BioShapes >>> >>> Although there are 27 unique cloners on GitHub, I am >>> still looking for contributors and collaborators. I >>> would appreciate any collaborations to develop it >>> further. I can be contacted both by email and on GitHub. >>> >>> >>> B.) Documentation Tools >>> >>> Is there a succinct, but sufficiently informative >>> description of documentation tools? I find that >>> including the documentation in the source files is very >>> distracting. I would prefer to have only basic comments >>> in the source files and an expanded documentation in a >>> separate location. >>> >>> This question may be more appropriate for the >>> R-package-devel list. I can move the 2nd question to >>> that list. >>> >>> ### >>> >>> As the biological sciences are very vast, I would be >>> very happy for collaborators on the development of this >>> package. Examples with existing shapes are available in >>> (but are unfortunately not documented): >>> >>> Man/examples/Examples.Man.R R/Examples.R >>> R/Examples.Cells.R tests/experimental/* >>> >>> >>> Many thanks, >>> >>> Leonard >>> >>> ______________________________________________ >>> R-help at r-project.org mailing list -- To UNSUBSCRIBE and >>> more, see https://stat.ethz.ch/mailman/listinfo/r-help >>> PLEASE do read the posting guide >>> http://www.R-project.org/posting-guide.html >>> <http://www.R-project.org/posting-guide.html> and >>> provide commented, minimal, self-contained, reproducible >>> code. >>> >> [[alternative HTML version deleted]] >> >> ______________________________________________ >> R-help at r-project.org mailing list -- To UNSUBSCRIBE and >> more, see https://stat.ethz.ch/mailman/listinfo/r-help >> PLEASE do read the posting guide >> http://www.R-project.org/posting-guide.html and provide >> commented, minimal, self-contained, reproducible code. > -- > Sent from my phone. Please excuse my brevity. > ______________________________________________ > R-help at r-project.org mailing list -- To UNSUBSCRIBE and > more, see https://stat.ethz.ch/mailman/listinfo/r-help > PLEASE do read the posting guide > http://www.R-project.org/posting-guide.html and provide > commented, minimal, self-contained, reproducible code.
Thank you very much for all the responses; especially Duncan's guidance. I will add some further ideas on workflows below. There were quite a few views on GitHub; but there is not much to see, as there is absolutely no documentation.? I have added in the meantime a basic example: https://github.com/discoleo/BioShapes/blob/main/Examples.Bioshapes.png The actual code can do a lot more. ############ Some ideas on workflows: 1. Most code is written as C/C++; the R code is a thin wrapper around the C/C++ functions It is practical to embed the documentation with the R code - as there is no complex code anyway. The same may apply for small packages. 2. Complex R code The comments may clutter the code. It is also difficult to maintain this documentation, as the comments are less easily readable. Separating the documentation from the code is a good idea. Unfortunately, this is not so obvious when you start working on your first package. Many thanks, Leonard On 9/4/2023 5:47 AM, Jeff Newmiller wrote:> Leonard... the reason roxygen exists is to allow markup in source files to be used to automatically generate the numerous files required by standard R packages as documented in Writing R Extensions. > > If your goal is to not use source files this way then the solution is to not use roxygen at all. Just create those files yourself by directly editing them from scratch. > > On September 3, 2023 7:06:09 PM PDT, Leonard Mada via R-help <r-help at r-project.org> wrote: >> Thank you Bert. >> >> >> Clarification: >> >> Indeed, I am using an add-on package: it is customary for that package - >> that is what I have seen - to have the entire documentation included as >> comments in the R src files. (But maybe I am wrong.) >> >> >> I will try to find some time over the next few days to explore in more >> detail the R documentation. Although, I do not know how this will >> interact with the add-on package. >> >> >> Sincerely, >> >> >> Leonard >> >> >> On 9/4/2023 4:58 AM, Bert Gunter wrote: >>> 1. R-package-devel is where queries about package protocols should go. >>> >>> 2. But... >>> "Is there a succinct, but sufficiently informative description of >>> documentation tools?" >>> "Writing R Extensions" (shipped with R) is *the* reference for R >>> documentation. Whether it's sufficiently "succinct" for you, I cannot >>> say. >>> >>> "I find that including the documentation in the source files is very >>> distracting." >>> ?? R documentation (.Rd) files are separate from source (.R) files. >>> Inline documentation in source files is an "add-on" capability >>> provided by optional packages if one prefers to do this. Such packages >>> parse the source files to extract the documentation into the .Rd >>> files/ So not sure what you mean here. Apologies if I have misunderstood. >>> >>> " I would prefer to have only basic comments in the source >>> files and an expanded documentation in a separate location." >>> If I understand you correctly, this is exactly what the R package >>> process specifies. Again, see the "Writing R Extensions" manual for >>> details. >>> >>> Also, if you wish to have your package on CRAN, it requires that the >>> package documents all functions in the package as specified by the >>> "Writing ..." manual. >>> >>> Again, further questions and elaboration should go to the >>> R-package-devel list, although I think the manual is really the >>> authoritative resource to follow. >>> >>> Cheers, >>> Bert >>> >>> >>> >>> On Sun, Sep 3, 2023 at 5:06?PM Leonard Mada via R-help >>> <r-help at r-project.org> wrote: >>> >>> Dear R-List Members, >>> >>> I am looking for collaborators to further develop the BioShapes >>> almost-package. I added a brief description below. >>> >>> A.) BioShapes (Almost-) Package >>> >>> The aim of the BioShapes quasi-package is to facilitate the >>> generation >>> of graphical objects resembling biological and chemical entities, >>> enabling the construction of diagrams based on these objects. It >>> currently includes functions to generate diagrams depicting viral >>> particles, liposomes, double helix / DNA strands, various cell types >>> (like neurons, brush-border cells and duct cells), Ig-domains, as >>> well >>> as more basic shapes. >>> >>> It should offer researchers in the field of biological and chemical >>> sciences a tool to easily generate diagrams depicting the studied >>> biological processes. >>> >>> The package lacks a proper documentation and is not yet released on >>> CRAN. However, it is available on GitHub: >>> https://github.com/discoleo/BioShapes >>> >>> Although there are 27 unique cloners on GitHub, I am still looking >>> for >>> contributors and collaborators. I would appreciate any >>> collaborations to >>> develop it further. I can be contacted both by email and on GitHub. >>> >>> >>> B.) Documentation Tools >>> >>> Is there a succinct, but sufficiently informative description of >>> documentation tools? >>> I find that including the documentation in the source files is very >>> distracting. I would prefer to have only basic comments in the source >>> files and an expanded documentation in a separate location. >>> >>> This question may be more appropriate for the R-package-devel list. I >>> can move the 2nd question to that list. >>> >>> ### >>> >>> As the biological sciences are very vast, I would be very happy for >>> collaborators on the development of this package. Examples with >>> existing >>> shapes are available in (but are unfortunately not documented): >>> >>> Man/examples/Examples.Man.R >>> R/Examples.R >>> R/Examples.Cells.R >>> tests/experimental/* >>> >>> >>> Many thanks, >>> >>> Leonard >>> >>> ______________________________________________ >>> R-help at r-project.org mailing list -- To UNSUBSCRIBE and more, see >>> https://stat.ethz.ch/mailman/listinfo/r-help >>> PLEASE do read the posting guide >>> http://www.R-project.org/posting-guide.html >>> <http://www.R-project.org/posting-guide.html> >>> and provide commented, minimal, self-contained, reproducible code. >>> >> [[alternative HTML version deleted]] >> >> ______________________________________________ >> R-help at r-project.org mailing list -- To UNSUBSCRIBE and more, see >> https://stat.ethz.ch/mailman/listinfo/r-help >> PLEASE do read the posting guide http://www.R-project.org/posting-guide.html >> and provide commented, minimal, self-contained, reproducible code.