[WIP] JOSS - Improve Documentation for vtkvmtk C++ classes#295
Merged
Conversation
This is requested by the JOSS reviewers for paper acceptance
…umentation generation instructions to the contributor guidelines
fixed comment style for doxygen generation
Update some of the finite element solver assembler documentation, some segmentation documentation, and fixup a few typos. At this point most of the C++ class reference (that we want people playing with) should have sufficient explainations attached to them.
…webpage extensions from html to xhtml on everyone didn't seem like a great idea
Member
Author
|
Doc strings have been added to core library classes and methods. The most extensive explanations have been provided for classes which deal with generation, analysis, and post processing of centerlines as the data models and paradigms appear to be fairly unique to this subfield of medically focused computational work. |
36 tasks
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Addresses point two of #288 (comment) for openjournals/joss-reviews#745.
Initial work of improving vtkvmtk c++ documentation.
For transparency in the review process: this is a collaborative effort between @lantiga and myself. I have begun fixing up the documentation and adding docstrings for classes whose functions are straightforward enough to understand with just a quick glance through the code. In order to expedite this process (so as to not hold up the review), I am going to be recording a (private) video call between @lantiga and myself in which he will go rapid fire through the more complex files and give a brief description of their function. I will later transcribe the contents of the recording into docstrings for each method. @Kevin-Mattheus-Moerman, can you please confirm (or advise on alternatives) that this action and disclosure of such an event falls in line with the JOSS Code of Conduct and general sentiment behind the open nature of the JOSS review process?
@lantiga, you'll be happy to know that the doxygen project builds correctly. The one caveat is that you have to explicitly pass
-DBUILD_DOCUMENTATION=ONas an argument to cmake during the initial cmake generation step. This option cannot currently be set via the cmake curses interface or at any time after the first call to cmake in the build directory.As a reminder for myself before merging this:
Complete class level documentation
Add an option ("toggleable" by the curses interface or cmake-gui) for enabling the
BUILD_DOCUMENTATIONflag without having to explicitly pass it as -DBUILD_DOCUMENTATION=ONat the time when the CMake project is first generated.Add documentation stating how once the project is built with
BUILD_DOCUMENTATION=ON, you still need to run doc_makeall.sh from the terminal. The configure file is placed within the build directory at:build-directory/VMTK-Build/vtkVmtk/Utilities/Doxygen/doc_makeall.sh. To update the website doc you need to copy the contents ofbuild-directory/VMTK-Build/vtkVmtk/Utilities/Doxygen/doc/html/into the following subdirectory of the vmtk/vmtk.github.com repo:vmtk.github.com/doc/html/Add documentation stating that in order to build the doxygen documentation you must have doxygen, graphviz, and a LaTeX distribution on your system in addition to the normal build requirements.