[R] [Pkg-Collaboratos] BioShapes Almost-Package

[Leonard Mada]

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 using 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 using 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 using 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 using 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.