Refactor Inlet's DocWriter interface, add support for documenting provided values #446
Conversation
There was a problem hiding this comment.
Thanks @joshessman-llnl -- this is a nice improvment.
Are the callback functions added to the tables? (Perhaps I missed it).
Ideally, they would list their signature in addition to other metadata.
Not currently - I'll tag this as an issue since I would prefer to do that as a separate PR in the interest of keeping PRs reasonably sized when possible. |
| std::ofstream m_outFile; | ||
| std::ostringstream m_oss; | ||
| // This is needed to preserve the traversal order of the Inlet::Tables | ||
| std::vector<std::string> m_inletTablePathNames; | ||
| std::unordered_map<std::string, TableData> m_rstTables; | ||
| std::string m_fileName; | ||
| // Used for the RST tables for fields | ||
| std::vector<std::string> m_colLabels; |
There was a problem hiding this comment.
Minor: Since you already depend on Sidre, you might consider using a sidre::MapCollection for this.
The data is stored in an integer-indexed array, but entries can be indexed by strings.
See: https://github.com/LLNL/axom/blob/develop/src/axom/sidre/core/MapCollection.hpp
There was a problem hiding this comment.
I agree that something like this might be useful, but the use of raw pointers as the stored item instead of objects themselves would require introducing manual memory management here (I think) since I want the data to be owned by the container.
I'll have to tweak this logic a bit anyways when I add callback function documentation, so possibly a more elegant solution will present itself.
| ******************************************************************************* | ||
| * \file Writer.hpp | ||
| * | ||
| * \brief This file contains the abstract base class definition of Writer. |
There was a problem hiding this comment.
I like this abstraction.
I can imagine a use-case where one would want to output each top-level table in a separate file.
|
LGTM |
|
LGTM |
Summary
DocWriterinterface to be more descriptive and renames it to justWriterCurrently the
DocWriterinterface only requires that implementers implement avoid writeDocumentation(void), which isn't a particularly descriptive signature. This PR introducesdocumentTable(const Table&)andfinalize()methods to the interface which implementers use to document a singleTableand write/flush documentation, respectively.This allows the base
Inletclass to manage traversal through the Inlet tree/hierarchy (which is writer-agnostic).This PR also extends the SphinxDocWriter to document the provided values. This is reflected in the updated Sphinx page with the sample output. Note that Inlet does not keep track of whether the provided value was just the default value (i.e., it was not provided by the user), so the generated documentation also does not make this distinction.