Enhance Documentation #28
Merged
Conversation
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
added 5 commits
March 4, 2024 17:20
…TypeDescriptor Removed specific BinaryHeaderDescriptor and TraceHeaderDescriptor classes, instead utilizing StructuredDataTypeDescriptor. This change simplifies the codebase by reducing redundancy and incorporating a more general class where specific ones were previously used. This refactoring also involved updating tests and other parts where the removed classes were implemented.
The commit enhances the docstring for the function that customizes an existing SEG-Y descriptor. The new docstring includes details about the arguments it takes and the return value, providing clearer information for developers on how to use this function.
The documentation skeleton has been revamped for better clarity and understanding. `header.md` has been deleted, `data_type.md` is newly added, and minor edits in `trace.md` and `index.md` files. The changes are aimed to better illustrate the core concepts and structures in data models.
This commit introduces documentation for the SEG-Y file structure to the data models sections. It provides a comprehensive overview and details about various components of the SEG-Y file format, such as SEGY-standard, text and binary file headers, trace and extended text headers. The information outlined can be beneficial for users for a better understanding of the SEG-Y seismic data files in terms of both reading and processing them programmatically.
Improved clarity and detail of docstrings in data_type.py. The updates include changes to descriptions for enumeration and descriptor classes. Additionally, example usage has also been incorporated for these classes, providing valuable context and clarification for developers on how these functions operate.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #28 +/- ##
==========================================
- Coverage 81.14% 80.91% -0.23%
==========================================
Files 30 30
Lines 1082 1069 -13
Branches 136 136
==========================================
- Hits 878 865 -13
Misses 171 171
Partials 33 33 ☔ View full report in Codecov by Sentry. |
added 11 commits
March 4, 2024 19:42
The commit modifies two documentation strings. In `data_type.py`, it updates references to class components to improve linkage. Meanwhile, in `segy.py`, it rewords the description of SegyStandard for clarity.
The commit updates the byte range notation for different fields in the source code documentation. Changes are purely stylistic, transitioning from using a '-' delimiter to using detailed sentences for clarity. The byte ranges themselves are unchanged.
Enhanced the class and method docstrings in src/segy/file.py to provide a more detailed description of the module's logic. This includes information on how to open a SEG-Y file based on a custom spec as well as the purpose of the SegyFile class and its various accessors. Additional comments also address a potential issue for further investigation.
The autodoc settings for pydantic models and settings have been updated in the conf.py file. This includes changes to member ordering and the visibility of summaries for fields and validators.
In the 'SegyFileSettings' class, the 'REVISION' field type was updated to accept 'int', 'float', or 'None' types. Additionally, the instantiation of 'BINARY' was modified utilizing 'default_factory' inside the 'Field' instance.
The API reference documentation has been updated with new sections for more clarity. Changes include an enriched explanation of the SEG-Y File class, along with added details for various configurations like SegyFileSettings, SegyBinaryHeaderSettings, ExtendedTextHeaderSetting, SampleIntervalSetting, and SamplesPerTraceSetting.
A new documentation page about settings management was added. It provides details about how to initialize and handle instances of SegyFileSettings. It further explains how environment variables can be used to configure SegaFileSettings.
The '\' line continuation character was removed from the text in `docs/installation.md`. This simplifies the readability of the document and prevents any potential rendering issues.
The commit corrects a typo in our project README file, tidies up the format and also adds direct pip and PyPi links. This enhancement is intended to facilitate easier access to Python packages and therefore improve the user's experience.
ta-hill
reviewed
Mar 5, 2024
ta-hill
reviewed
Mar 5, 2024
ta-hill
reviewed
Mar 5, 2024
Clarified the USE_PANDAS setting in the documentation. Added information about its non-applicability to trace data, explaining that trace data is always returned as Numpy arrays. Also mentioned that the option to use Numpy for headers is currently disabled but will be available in a future release.
ta-hill
approved these changes
Mar 5, 2024
added 2 commits
March 5, 2024 12:49
The documentation for seismic traces in data models has been significantly expanded. The new documentation includes comprehensive definitions and explanations, as well as examples for defining a trace, trace header descriptor, and trace data descriptor. It also introduces how to create a trace descriptor both programmatically and from JSON.
…umentation links SampleIntervalSetting was removed from the API reference doc. The trace documentation has been improved with precise links, replacing the Trace Header and Trace Data link references with trace-header-descriptor and trace-data-descriptor. Duplicate SegyFileSettings link reference from settings file deleted.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Rendered docs with updates here: https://segy--28.org.readthedocs.build/en/28/