-
Notifications
You must be signed in to change notification settings - Fork 6
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
PLEP7: top level package structure #26
Merged
rocco8773
merged 67 commits into
PlasmaPy:master
from
rocco8773:PLEP7_top_level_package_structure
May 15, 2020
Merged
Changes from 20 commits
Commits
Show all changes
67 commits
Select commit
Hold shift + click to select a range
9fb6cfb
initial commit for PLEP-0007...fill-out summary and abstract
rocco8773 1382c2c
start outlining `Detailed Description`
rocco8773 80d256c
testing a table
rocco8773 94d4336
testing a table design
rocco8773 676c6d9
testing a table design
rocco8773 dd1af5b
testing a line blocks in table design
rocco8773 5c55600
testing a line blocks in table design
rocco8773 ddbc634
place all sup-packages into table
rocco8773 a501334
add Tulasi Parashar, Steve Vincena, and Nick Murphy to authors
rocco8773 637ba4e
defining scope of `plasmapy.utils`
namurphy 930e0fc
defining scope of `plasmapy.tests`
rocco8773 2855a77
defining scope of `plasmapy.simulations`
rocco8773 9d084ad
testing :additional PLEP: look
rocco8773 d3b3d80
add to abstract...this PLEP only defines the general scope of top-lev…
rocco8773 c6265c1
add :sub-package PLEP: entry to each sub-package
rocco8773 32d3681
remove bullet point list
rocco8773 5a15ce4
defining scope of `plasmapy.formulary`
rocco8773 ada2eeb
defining scope of `plasmapy.analysis`
rocco8773 a0389c7
add `` to get proper inline code typesetting
rocco8773 2aa0677
Fix a few typos
StanczakDominik 792292a
add scope to `plasmapy.particle`
rocco8773 7b2f447
Merge remote-tracking branch 'fork/PLEP7_top_level_package_structure'…
rocco8773 0bf60ba
add scope to `plasmapy.dispersion`
rocco8773 37332a8
add scope to `plasmapy.diagnostics`
rocco8773 a6bf2d3
replaced :sub-package PLEP: with just :PLEP: ...the flag/key is alrea…
rocco8773 7d34ff6
add scope for `plasmapy.plasma`
rocco8773 4eede0f
add scope for `plasmapy.examples`
rocco8773 b0cb96d
remove `plasmapy.examples`, pluralize `plasmapy.particles`
rocco8773 617fd8e
fix table
rocco8773 ba24722
trying to link to table row
rocco8773 68ebe71
still trying to hyperlink table
rocco8773 280897d
add links to all sub-package descriptions in the table
rocco8773 d68cc4d
pluralize sub-package plasmapy.plasmas
rocco8773 e6e3c56
singular-ize sub-package plasmapy.plasmas -> plasmapy.plasma
rocco8773 f2e5cf5
outline addons subpackage
rocco8773 e6ce0bd
update description of all sub-packages; remove sub-package "examples"
rocco8773 36a5a96
remove section "Alternatives"
rocco8773 87d0f94
fix table boarders
rocco8773 7ab5a33
write section "Decision Rationale"
rocco8773 87a2509
write sections "Implementation" and "Issues, Pull Requests, and Branc…
rocco8773 b982d7b
a little rewording
rocco8773 fd055fe
add to the reasoning "help users navigate to the functionality they n…
rocco8773 a08cdc8
add PLEP to the README table
rocco8773 1bc8c02
update given Nicks code review
rocco8773 8054ee4
re-word description of the dispersion section
rocco8773 e793c3f
wording clairfication for plasmapy.analysis description
rocco8773 a7a4469
re-word plasmapy.simulation description
rocco8773 157945a
Utilities is plural, not possessive
rocco8773 5b80c73
attempting to make tables look clean when rendering rst and convertin…
rocco8773 0092bb8
a few more changes to see how "notes" appear
rocco8773 c8fba5e
update analysis table
rocco8773 1219647
improve some wording and style formatting
rocco8773 e92d515
reformat tables so they look good as rst and pdf...pandoc does not su…
rocco8773 3ab4e72
how do section look vs table headings
rocco8773 0dcafe4
Revert "how do section look vs table headings"
rocco8773 0b3be4f
add clause about exempting extensible packages
rocco8773 a2c5049
manually add a table of contents since pandoc does not support the RS…
rocco8773 f794536
reduce wordiness
rocco8773 46b043c
add DOI and last revised date
rocco8773 fa9d36f
delete missed comma
rocco8773 32f13ff
steve -> stephen
rocco8773 57ebe38
add DOI to README
rocco8773 f5e0df7
Typo fix
StanczakDominik 0da36bb
new code should be thoroughly and exhaustively reviewed before taking…
rocco8773 d049a44
Merge remote-tracking branch 'fork/PLEP7_top_level_package_structure'…
rocco8773 e7e907a
update last revised date and mark as accepted
rocco8773 aafbecb
capitalize Standard
rocco8773 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,189 @@ | ||
| =============================================== | ||
| PLEP-0007 – Structure of Top-Level Sub-Packages | ||
| =============================================== | ||
|
|
||
| +-------------------+---------------------------------------------+ | ||
| | PLEP | 7 | | ||
| +===================+=============================================+ | ||
| | author(s) | Erik T. Everson, Tulasi Parashar, | | ||
| | | Steve Vincena, Nicholas A. Murphy | | ||
| +-------------------+---------------------------------------------+ | ||
| | contact email | [email protected] | | ||
| +-------------------+---------------------------------------------+ | ||
| | date created | 2019-10-27 | | ||
| +-------------------+---------------------------------------------+ | ||
| | date last revised | *YYYY-MM-DD* | | ||
| +-------------------+---------------------------------------------+ | ||
| | type | standard | | ||
| +-------------------+---------------------------------------------+ | ||
| | status | in preparation | | ||
| +-------------------+---------------------------------------------+ | ||
| | DOI | | | ||
| | | | | ||
| +-------------------+---------------------------------------------+ | ||
|
|
||
| Abstract | ||
| ======== | ||
|
|
||
| This PLEP defines the top-level structure of ``PlasmaPy`` (i.e. | ||
| ``plasmapy.<subpackage>``). Its intent is to name the top-level | ||
| sub-packages and define the general scope of the code they encompass. | ||
| Sub-package details are left to be defined in package focused | ||
| PLEPs, which should *NOT* conflict with this PLEP. This | ||
| structure should help developers decided where new code should be | ||
| placed and keep the top-level namespace from getting bloated. If | ||
| new code does NOT fall within the current framework, then this PLEP | ||
| needs to be modified/updated accordingly before any new top-level | ||
| sub-packages are created. | ||
|
|
||
| Detailed Description | ||
| ==================== | ||
|
|
||
| Why? | ||
| ---- | ||
|
|
||
| By defining a top-level sub-package namespace, developers are better | ||
| directed to where code can be added and the ``PlasmaPy`` | ||
| **Coordinating Committee** can better manage package bloat. | ||
|
|
||
| Top-Level Sub-Packages | ||
| ---------------------- | ||
|
|
||
| +------------------------------------------------------------------------------+ | ||
| | **analysis** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/analysis/`` | | ||
| | :access: ``plasmapy.analysis`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | A collection of functions, classes, and sub-packages focused on providing | | ||
| | analysis techniques that can be applied to data collected from a variety | | ||
| | of sources (simulation, experimental, space, etc.). | | ||
| | | | ||
| | The focus of an analysis routine should be made as broad as possible. | | ||
| | When the routine's functionality becomes highly-tailored to its | | ||
| | application, then it should be placed into an appropriate explicit | | ||
| | namespace. | | ||
rocco8773 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| +------------------------------------------------------------------------------+ | ||
| | **diagnostics** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/diagnostics/`` | | ||
| | :access: ``plasmapy.diagnostics`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | | blah blah blah | | ||
| | | blah blah blah | | ||
| +------------------------------------------------------------------------------+ | ||
| | **dispersion** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/dispersion/`` | | ||
| | :access: ``plasmapy.dispersion`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | | blah blah blah | | ||
| | | blah blah blah | | ||
| +------------------------------------------------------------------------------+ | ||
| | **examples** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/examples/`` | | ||
| | :access: ``plasmapy.examples`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | | blah blah blah | | ||
| | | blah blah blah | | ||
rocco8773 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| +------------------------------------------------------------------------------+ | ||
| | **formulary** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/formulary/`` | | ||
| | :access: ``plasmapy.formulary`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | A collection of functions, classes, and sub-packages that provide | | ||
rocco8773 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | mathematical and scientific formulas for calculating physical parameters | | ||
| | of various plasmas. | | ||
| +------------------------------------------------------------------------------+ | ||
| | **particle** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/particle/`` | | ||
| | :access: ``plasmapy.particle`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | | blah blah blah | | ||
| | | blah blah blah | | ||
StanczakDominik marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| +------------------------------------------------------------------------------+ | ||
| | **plasma** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/plasma/`` | | ||
| | :access: ``plasmapy.plasma`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | | blah blah blah | | ||
| | | blah blah blah | | ||
| +------------------------------------------------------------------------------+ | ||
| | **simulation** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/simulation/`` | | ||
| | :access: ``plasmapy.simulation`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | A collection of functions, classes, and sub-packages focused on | | ||
| | interfacing with simulations and/or running simulations. | | ||
| | | | ||
| | If a new feature falls under the scope of the ``analysis`` and/or | | ||
| | ``diagnostics`` sub-packages, then the feature should be included one of | | ||
rocco8773 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | respective packages. For example, a synthetic diagnostic should be | | ||
| | included in the ``plasmapy.diagnostics`` sub-package. | | ||
| +------------------------------------------------------------------------------+ | ||
| | **tests** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/tests/`` | | ||
| | :access: ``plasmapy.tests`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | A collection of tests for top-level modules (i.e. functions and classes | | ||
| | defined in top-level ``.py`` files). | | ||
rocco8773 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| +------------------------------------------------------------------------------+ | ||
| | **utils** | | ||
| +------------------------------------------------------------------------------+ | ||
| | :directory: ``./plasmapy/utils/`` | | ||
| | :access: ``plasmapy.utils`` | | ||
| | :sub-package PLEP: | | ||
| | :scope: | | ||
| | A collection of "utility" functions and classes to help us write | | ||
| | (what we try to think of as) clean, readable, and informative code. | | ||
| | | | ||
| | This collection does not provide any physics tools, instead it is | | ||
| | focused on providing package development tools. | | ||
| +------------------------------------------------------------------------------+ | ||
|
|
||
| Implementation | ||
| ============== | ||
|
|
||
| *Describe the steps necessary to implement this PLEP, if necessary.* | ||
|
|
||
| Issues, Pull Requests, and Branches | ||
| =================================== | ||
rocco8773 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| *Provide repository links related to this PLEP, and include | ||
| descriptions.* | ||
|
|
||
| Backward Compatibility | ||
| ====================== | ||
|
|
||
| This PLEP will NOT maintain backward compatibility. | ||
|
|
||
| Alternatives | ||
| ============ | ||
rocco8773 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| *Summarize alternative possibilities to address (or not address) the | ||
| problem described in this PLEP, if necessary.* | ||
|
|
||
| Decision Rationale | ||
| ================== | ||
|
|
||
| *Summarize the discussion on this PLEP and describe the reasoning | ||
| behind the decision, if necessary.* | ||
|
|
||
| *Not all PLEPs require all of these sections, and occasionally | ||
| additional sections may be necessary. Emphasized text should be | ||
| deleted.* | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Or, presumably, the code should be ajusted to fit this framework?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've reworded this a bit to indicate that amending the PLEP should be the last resort option. I assumed that would happen by default, since it will always be easier to conform code than to amend the PLEP and get it accepted.
This statement is here more so for the off chance that we overlooked something that should be a top-level package.