New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Create documentation paradigm for modules #125

Closed
eliotmcintire opened this Issue Jan 12, 2015 · 5 comments

Comments

Projects
None yet
2 participants
@eliotmcintire
Contributor

eliotmcintire commented Jan 12, 2015

This is the general issue for #21 #22 #23 #24 #25

@eliotmcintire eliotmcintire added this to the v0.5.0 milestone Jan 12, 2015

@eliotmcintire

This comment has been minimized.

Contributor

eliotmcintire commented Jan 12, 2015

I started with using roxygenize2 ideas, but it may need more thought. Maybe it is fine. See commit a76db0e

@achubaty

This comment has been minimized.

Contributor

achubaty commented Jan 13, 2015

Module metadata at top of the module's .R file should include (at minimum) the following metadata:

  1. brief description of the module
  2. author and contact info
  3. identify the type of license under which the module can be used (see below)
  4. identify all additional files that document the module (see below)

Module distribution

Hosted in a separate GitHub repo (PredictiveEcology/SpaDES-modules), with each module contained in a separate subdirectory. The entire contents of a module subdir can be distributed as .zip file. Each module sub directory is named after the module and does not contain version info (this will be provided as part of the metadata, etc. per below). Distributed (and archived) .zip files could be named with the version number if desired.

Module data will NOT be included/hosted in our repo. They must be accessible elsewhere, and code/instructions for this step should be included in the module documentation.

Modules can be contributed to our repo via pull requests, which also provides easier quality assurance on our part with respect to contributed modules' structure and documentation.

Module directory structure:

    /
    |_ moduleName/
        |_ moduleName.R            # the actual module code file, incl. module metadata
        |_ moduleName.Rmd          # longform documentation and usage info, etc.
        |_ citation.bib            # properly formatted bibtex citation for the module
        |_ LICENSE                 # license file describing the allowed usage etc. of the module
        |_ README                  # incl. module metadata in addition to version change info, etc.
    |_ moduleName.zip
    |_ moduleName0.1.0.zip

achubaty added a commit that referenced this issue Feb 5, 2015

revised dependency object (class) definitions
part of #125 & #126

- delineate module vs object properties/metadata
- need to convert s3 `person` class to S4 (*incomplete*)
@eliotmcintire

This comment has been minimized.

Contributor

eliotmcintire commented Mar 4, 2015

All done except .zip files because they are not relevant until the module has real files worth zipping. 3e6608d 697322f 7c74e10.

@eliotmcintire

This comment has been minimized.

Contributor

eliotmcintire commented Mar 4, 2015

Still need to change the simInit function, so that path argument is the base folder for modules, and modules are subfolders within that.

achubaty added a commit that referenced this issue Mar 4, 2015

update `simInit` with new module structure
also updated sample modules

closes #125

TO DO: sample module documentation (#23, #24, #25)
@achubaty

This comment has been minimized.

Contributor

achubaty commented Mar 4, 2015

other than updating the sample module docs as noted in 3b1b0e7, I think this can be closed.

@achubaty achubaty closed this Mar 4, 2015

@achubaty achubaty modified the milestones: v0.6.0, v0.5.0 Mar 4, 2015

achubaty added a commit that referenced this issue Mar 5, 2015

achubaty added a commit that referenced this issue Mar 5, 2015

progress(?) on #125 and #126
ISSUE: still grappling with environments

`source()` evaluates the code in the env given by `local`
- `local=TRUE` means parent frame

`eval()` evaluates the code in the given env but it’s not persistent???

achubaty added a commit that referenced this issue Mar 5, 2015

back to basics...
part of #125 and #126

- use two separate files for module metadata & code

    - `metadata.R` sourced to local env.
    - `moduleName.R` code sourced to `.GlobalEnv`

- update module template and sample modules to reflect this
- remove function `prevArgs` and reintegrate code in `.objectNames`
- separate dependency classes and methods into two R files

achubaty added a commit that referenced this issue Mar 18, 2015

passes `R CMD check`
* resolved in this branch: #117, #118, #125, #126
* updated `checkPath` and its test

* however, there are still a few notes to deal with
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment