Commit bbc2997b authored by Ciarán Ó Rourke's avatar Ciarán Ó Rourke
Browse files

Squashed 'external/doxygen-xml-parser/' content from commit be8e4fb3

git-subtree-dir: external/doxygen-xml-parser
git-subtree-split: be8e4fb35ac8b682145d9d1301d74750db50d732
parents
.DS_Store
__pycache__
# Doxygen XML Parser
This project can be used to convert the [Doxygen](http://www.doxygen.nl/) XML output of a C++ project into Markdown files.
In the current state the most important things are supported and tested on one specific project.
## Project structure
The project consits of the source code in the folder `src`, some tests that do not work at all at the moment and are rather misguided in their whole idea in `test` and an example output belonging to the [ExSeisDat](https://git.ichec.ie/oilgas/ExSeisDat) project in `example`.
The source code consists of two main python executables: `xml_to_json_parser.py` and `json_to_Markdown_converter.py`:
### xml_to_json_parser
This script can be used to create a json file in the current working directory, that will contain all documented elements found in the xml folder.
Usage:
```
python3 xml_to_json_parser.py path/to/doxygen/xml output.json
```
The path must point to the folder containing the index.xml file created by Doxygen (and can be relative or absolute). The `output.json` will be the name of the JSON file created by the script.
Information on additional parameters can be accessed over `python3 xml_to_json_parser.py -h`
### json_to_Markdown_converter
After generating the json file, the data can be printed to Markdown files, following the C++ namespace logic.
Usage:
```
python3 json_to_Markdown_converter.py path/to/json/file/output.json path/to/doc/folder
```
The first argument is the output file from xml_to_json_parser, the second argument should be the folder in which the documentation will be created.
Information on additional parameters can be accessed over `python3 json_to_Markdown_converter.py -h`
## Additional Notes:
* As mentioned earlier, the tests are in a very deprecated state because I was unhappy with their whole structure. In theory they can be executed by `python3 -m unittest testtype`, where `testtype` is one of
* structure
* description
* reference
* regression
* feature
* The scripts will create log files in the working directory with log level info. The level of verbosity and the name of the log file can be changed over additional command line arguments
* Since this is tested with only two C++ projects I expect it to break with structures, concepts and usecases I did not anticipate.
This diff is collapsed.
# <a name='exseis-flow' /> exseis::flow
ExSeisFlow: A High-Performance, Parallel Seismic Workflow library.
The ExSeisFlow library is a seismic data workflow library that leverages ExSeisPIOL for fast, parallel I/O, and uses workflow optimizations and smart caching to minimize I/O bandwidth and memory usage.
## Classes
| Name | Description |
| ---- | ---- |
| [Set](./Set.md) | The internal set class. |
# <a name='exseis' /> exseis
The ExSeisDat library: High-Performance, Parallel Processing of Seismic Data.
## Namespaces
| Name | Description |
| ---- | ---- |
| [flow](./flow/index.md) | ExSeisFlow: A High-Performance, Parallel Seismic Workflow library. |
| [piol](./piol/index.md) | ExSeisPIOL: A High-Performance Parallel Seismic file I/O library. |
| [utils](./utils/index.md) | Utility classes and functions. |
[exseis-utils]:./utils/index.md
# <a name='exseis-piol-configuration-ExSeis' /> public exseis::piol::configuration::ExSeis
This class provides access to the [ExSeisPIOL][exseis-piol-configuration-ExSeisPIOL] class but with a simpler API.
## Inheritance:
Inherits from [exseis::piol::configuration::ExSeisPIOL][exseis-piol-configuration-ExSeisPIOL].
## Public Static Functions
| Name | Description |
| ---- | ---- |
| [make](#exseis-piol-configuration-ExSeis-make) | Constructor with optional maxLevel and which initialises MPI. |
## Public Functions
| Name | Description |
| ---- | ---- |
| [~ExSeis](#exseis-piol-configuration-ExSeis-~ExSeis) | [ExSeis][exseis-piol-configuration-ExSeis] Deleter. |
| [get_rank](#exseis-piol-configuration-ExSeis-get_rank) | Shortcut to get the commrank. |
| [get_num_rank](#exseis-piol-configuration-ExSeis-get_num_rank) | Shortcut to get the number of ranks. |
| [barrier](#exseis-piol-configuration-ExSeis-barrier) | Shortcut for a communication barrier. |
| [max](#exseis-piol-configuration-ExSeis-max) | Return the maximum value amongst the processes. |
| [assert_ok](#exseis-piol-configuration-ExSeis-assert_ok) | A function to check if an error has occured in the PIOL. If an error has occured the log is printed, the object destructor is called and the code aborts. |
## Private Functions
| Name | Description |
| ---- | ---- |
| [ExSeis](#exseis-piol-configuration-ExSeis-ExSeis) | The constructor is private! Use the ExSeis::make(...) function. |
## Public Static Functions
### <a name='exseis-piol-configuration-ExSeis-make' /> public std::shared_ptr< [ExSeis][exseis-piol-configuration-ExSeis] > exseis::piol::configuration::ExSeis::make (exseis::utils::Verbosity max_level=exseis::utils::Verbosity::none, MPI_Comm comm=MPI_COMM_WORLD)
Constructor with optional maxLevel and which initialises MPI.
#### Parameters:
| Direction | Type | Name | Description |
| ---- | ---- | ---- | ---- |
| in | MPI_Comm | comm | The MPI communicator |
| in | exseis::utils::Verbosity | max_level | The maximum log level to be recorded. |
#### Returns:
| Type | Description |
| ---- | ---- |
| std::shared_ptr< [ExSeis][exseis-piol-configuration-ExSeis] > | A shared pointer to a PIOL object. |
#### Qualifiers:
* static
* inline
[Go to Top](#exseis-piol-configuration-ExSeis)
## Public Functions
### <a name='exseis-piol-configuration-ExSeis-~ExSeis' /> public exseis::piol::configuration::ExSeis::~ExSeis ()
[ExSeis][exseis-piol-configuration-ExSeis] Deleter.
[Go to Top](#exseis-piol-configuration-ExSeis)
### <a name='exseis-piol-configuration-ExSeis-get_rank' /> public size_t exseis::piol::configuration::ExSeis::get_rank () const
Shortcut to get the commrank.
#### Returns:
| Type | Description |
| ---- | ---- |
| size_t | The comm rank. |
#### Qualifiers:
* const
[Go to Top](#exseis-piol-configuration-ExSeis)
### <a name='exseis-piol-configuration-ExSeis-get_num_rank' /> public size_t exseis::piol::configuration::ExSeis::get_num_rank () const
Shortcut to get the number of ranks.
#### Returns:
| Type | Description |
| ---- | ---- |
| size_t | The comm number of ranks. |
#### Qualifiers:
* const
[Go to Top](#exseis-piol-configuration-ExSeis)
### <a name='exseis-piol-configuration-ExSeis-barrier' /> public void exseis::piol::configuration::ExSeis::barrier () const
Shortcut for a communication barrier.
#### Qualifiers:
* const
[Go to Top](#exseis-piol-configuration-ExSeis)
### <a name='exseis-piol-configuration-ExSeis-max' /> public size_t exseis::piol::configuration::ExSeis::max (size_t n) const
Return the maximum value amongst the processes.
#### Parameters:
| Direction | Type | Name | Description |
| ---- | ---- | ---- | ---- |
| in | size_t | n | The value to take part in the reduction |
#### Returns:
| Type | Description |
| ---- | ---- |
| size_t | Return the maximum value amongst the processes |
#### Qualifiers:
* const
[Go to Top](#exseis-piol-configuration-ExSeis)
### <a name='exseis-piol-configuration-ExSeis-assert_ok' /> public void exseis::piol::configuration::ExSeis::assert_ok (const std::string &msg="") const
A function to check if an error has occured in the PIOL. If an error has occured the log is printed, the object destructor is called and the code aborts.
#### Parameters:
| Direction | Type | Name | Description |
| ---- | ---- | ---- | ---- |
| in | const std::string & | msg | A message to be printed to the log. |
If an error has occured the log is printed, the object destructor is called and the code aborts.
#### Qualifiers:
* const
[Go to Top](#exseis-piol-configuration-ExSeis)
## Private Functions
### <a name='exseis-piol-configuration-ExSeis-ExSeis' /> private exseis::piol::configuration::ExSeis::ExSeis (exseis::utils::Verbosity max_level=exseis::utils::Verbosity::none, MPI_Comm comm=MPI_COMM_WORLD)
The constructor is private! Use the ExSeis::make(...) function.
#### Parameters:
| Direction | Type | Name | Description |
| ---- | ---- | ---- | ---- |
| in | MPI_Comm | comm | The MPI communicator |
| in | exseis::utils::Verbosity | max_level | The maximum log level to be recorded. |
#### Returns:
| Type | Description |
| ---- | ---- |
| | A shared pointer to a PIOL object. |
[Go to Top](#exseis-piol-configuration-ExSeis)
[exseis-piol-configuration-ExSeis]:./ExSeis.md
[exseis-piol-configuration-ExSeisPIOL]:./ExSeisPIOL.md
# <a name='exseis-piol-configuration-ExSeisPIOL' /> public exseis::piol::configuration::ExSeisPIOL
The [ExSeisPIOL][exseis-piol-configuration-ExSeisPIOL] structure. A single instance of this structure should be created and passed to each subsequent PIOL object which is created.
## Inheritance:
Is inherited by [exseis::piol::configuration::ExSeis][exseis-piol-configuration-ExSeis].
## Public Attributes
| Name | Description |
| ---- | ---- |
| [log](#exseis-piol-configuration-ExSeisPIOL-log) | The [ExSeisPIOL][exseis-piol-configuration-ExSeisPIOL] logger. |
| [comm](#exseis-piol-configuration-ExSeisPIOL-comm) | The [ExSeisPIOL][exseis-piol-configuration-ExSeisPIOL] communication. |
## Protected Functions
| Name | Description |
| ---- | ---- |
| [ExSeisPIOL](#exseis-piol-configuration-ExSeisPIOL-ExSeisPIOL) | Constructor which initialized the logging level and MPI. |
## Public Functions
| Name | Description |
| ---- | ---- |
| [assert_ok](#exseis-piol-configuration-ExSeisPIOL-assert_ok) | A function to check if an error has occured in the PIOL. If an error has occured the log is printed, the object destructor is called and the code aborts. |
## Public Attributes
### <a name='exseis-piol-configuration-ExSeisPIOL-log' /> public exseis::piol::configuration::ExSeisPIOL::log
The [ExSeisPIOL][exseis-piol-configuration-ExSeisPIOL] logger.
[Go to Top](#exseis-piol-configuration-ExSeisPIOL)
### <a name='exseis-piol-configuration-ExSeisPIOL-comm' /> public exseis::piol::configuration::ExSeisPIOL::comm
The [ExSeisPIOL][exseis-piol-configuration-ExSeisPIOL] communication.
[Go to Top](#exseis-piol-configuration-ExSeisPIOL)
## Protected Functions
### <a name='exseis-piol-configuration-ExSeisPIOL-ExSeisPIOL' /> protected exseis::piol::configuration::ExSeisPIOL::ExSeisPIOL (exseis::utils::Verbosity max_level=exseis::utils::Verbosity::none, const Communicator_mpi::Opt &copt=Communicator_mpi::Opt())
Constructor which initialized the logging level and MPI.
#### Parameters:
| Direction | Type | Name | Description |
| ---- | ---- | ---- | ---- |
| in | const [Communicator_mpi::Opt][exseis-utils-communicator-Communicator_mpi-Opt] & | copt | An options structure for MPI |
| in | exseis::utils::Verbosity | max_level | The maximum log level to be recorded. |
[Go to Top](#exseis-piol-configuration-ExSeisPIOL)
## Public Functions
### <a name='exseis-piol-configuration-ExSeisPIOL-assert_ok' /> public void exseis::piol::configuration::ExSeisPIOL::assert_ok (const std::string &msg="") const
A function to check if an error has occured in the PIOL. If an error has occured the log is printed, the object destructor is called and the code aborts.
#### Parameters:
| Direction | Type | Name | Description |
| ---- | ---- | ---- | ---- |
| in | const std::string & | msg | A message to be printed to the log. |
#### Qualifiers:
* const
[Go to Top](#exseis-piol-configuration-ExSeisPIOL)
[exseis-piol-configuration-ExSeis]:./ExSeis.md
[exseis-piol-configuration-ExSeisPIOL]:./ExSeisPIOL.md
[exseis-utils-communicator-Communicator_mpi]:./../../utils/communicator/Communicator_mpi.md
[exseis-utils-communicator-Communicator_mpi-Opt]:./../../utils/communicator/Communicator_mpi/Opt.md#exseis-utils-communicator-Communicator_mpi-Opt
# <a name='exseis-piol-configuration' /> exseis::piol::configuration
Classes for storing configurations of the program.
## Classes
| Name | Description |
| ---- | ---- |
| [ExSeis](./ExSeis.md) | This class provides access to the [ExSeisPIOL][exseis-piol-configuration-ExSeisPIOL] class but with a simpler API. |
| [ExSeisPIOL](./ExSeisPIOL.md) | The [ExSeisPIOL][exseis-piol-configuration-ExSeisPIOL] structure. A single instance of this structure should be created and passed to each subsequent PIOL object which is created. |
[exseis-piol-configuration-ExSeis]:./ExSeis.md
[exseis-piol-configuration-ExSeisPIOL]:./ExSeisPIOL.md
# <a name='exseis-piol-file-Input_file' /> public exseis::piol::file::Input_file
The [`Input_file`][exseis-piol-file-Input_file] class is a generic interface for reading seismic data files.
## Inheritance:
Is inherited by [exseis::piol::file::Input_file_segy][exseis-piol-file-Input_file_segy].
## Special Member Functions
| Name | Description |
| ---- | ---- |
| [Input_file](#exseis-piol-file-Input_file-Input_file) | Default constructor: default. |
| [~Input_file](#exseis-piol-file-Input_file-~Input_file) | Virtual destructor. |
| [Input_file](#exseis-piol-file-Input_file-Input_file-1) | Copy constructor: delete. |
| [operator=](#exseis-piol-file-Input_file-operator=) | Copy assignment: delete. |
| [Input_file](#exseis-piol-file-Input_file-Input_file-2) | Move constructor: delete. |
| [operator=](#exseis-piol-file-Input_file-operator=-1) | Move assignment: delete. |
## Public Functions
| Name | Description |
| ---- | ---- |
| [file_name](#exseis-piol-file-Input_file-file_name) | Get the name of the file. |
| [read_file_headers](#exseis-piol-file-Input_file-read_file_headers) | Read the global file headers from the file. |
| [read_text](#exseis-piol-file-Input_file-read_text) | Read the human readable text from the file. |
| [read_ns](#exseis-piol-file-Input_file-read_ns) | Read the number of samples per trace. |
| [read_nt](#exseis-piol-file-Input_file-read_nt) | Read the number of traces in the file. |
| [read_sample_interval](#exseis-piol-file-Input_file-read_sample_interval) | Read the number of increment between trace samples. |
| [read_param](#exseis-piol-file-Input_file-read_param) | Read the trace parameters from offset to offset+sz of the respective trace headers. |
| [read_param_non_contiguous](#exseis-piol-file-Input_file-read_param_non_contiguous) | Read the traces specified by the offsets in the passed offset array. |
| [read_trace](#exseis-piol-file-Input_file-read_trace) | Read the traces from offset to offset+sz. |
| [read_trace_non_contiguous](#exseis-piol-file-Input_file-read_trace_non_contiguous) | Read the traces specified by the offsets in the passed offset array. Assumes Monotonic. |
| [read_trace_non_monotonic](#exseis-piol-file-Input_file-read_trace_non_monotonic) | Read the traces specified by the offsets in the passed offset array. Does not assume monotonic. |
## Special Member Functions
### <a name='exseis-piol-file-Input_file-Input_file' /> public exseis::piol::file::Input_file::Input_file ()=default
Default constructor: default.
[Go to Top](#exseis-piol-file-Input_file)
### <a name='exseis-piol-file-Input_file-~Input_file' /> public exseis::piol::file::Input_file::~Input_file ()
Virtual destructor.
#### Qualifiers:
* virtual
[Go to Top](#exseis-piol-file-Input_file)
### <a name='exseis-piol-file-Input_file-Input_file-1' /> public exseis::piol::file::Input_file::Input_file (const Input_file &)=delete
Copy constructor: delete.
[Go to Top](#exseis-piol-file-Input_file)
### <a name='exseis-piol-file-Input_file-operator=' /> public [Input_file][exseis-piol-file-Input_file] & exseis::piol::file::Input_file::operator= (const Input_file &)=delete
Copy assignment: delete.
#### Returns:
| Type | Description |
| ---- | ---- |
| [Input_file][exseis-piol-file-Input_file] & | A reference to the current instance. |
[Go to Top](#exseis-piol-file-Input_file)
### <a name='exseis-piol-file-Input_file-Input_file-2' /> public exseis::piol::file::Input_file::Input_file (Input_file &&)=delete
Move constructor: delete.
[Go to Top](#exseis-piol-file-Input_file)
### <a name='exseis-piol-file-Input_file-operator=-1' /> public [Input_file][exseis-piol-file-Input_file] & exseis::piol::file::Input_file::operator= (Input_file &&)=delete
Move assignment: delete.
#### Returns:
| Type | Description |
| ---- | ---- |
| [Input_file][exseis-piol-file-Input_file] & | A reference to the current instance. |