-
Notifications
You must be signed in to change notification settings - Fork 9
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
Rewrite the documentation #85
Conversation
Signed-off-by: John Pennycook <[email protected]>
The new documentation includes: - An introduction to Code Base Investigator - A worked tutorial with a sample code base - A reference page for codebasin Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
- Start all descriptions with a capital letter. - Rewrite some messages for clarity. - Consistently use <> syntax for metavars. Signed-off-by: John Pennycook <[email protected]>
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.
A few minor checks.
Also, I know we don't need it as a dependency persay, but do you need to document the version of sphinx
and extensions for building the docs somewhere?
1) Extract source files and compilation commands from a configuration file or compilation database. | ||
2) Build an AST representing which source lines of code (LOC) are associated with each specialization. | ||
3) Record which specializations are used by each platform. | ||
- Identify stale, legacy, code paths that are unused by any compilation target. |
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.
Does it directly? Or is it just by going through the gambit of finding residuals after running every possible target?
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.
The latter, I think. Code in a file that isn't touched by any platform in the configuration file gets associated with the empty platform set, and also called out as a percentage of SLOC:
---------------------------------------------
Platform Set LOC % LOC
---------------------------------------------
{} 2 4.88
{GPU 1} 1 2.44
{GPU 2} 1 2.44
{CPU 2} 1 2.44
{CPU 1} 1 2.44
{FPGA} 14 34.15
{GPU 2, GPU 1} 6 14.63
{CPU 1, CPU 2} 6 14.63
{FPGA, CPU 1, GPU 2, GPU 1, CPU 2} 9 21.95
---------------------------------------------
Code Divergence: 0.55
Unused Code (%): 4.88
Total SLOC: 41
We can't identify code we don't see at all.
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.
Maybe worth considering this as a feature in the future and have some routines that sniff the files to see if they could be code or not, and have a "lines of potentially stale code" value as well since unused code is still a maintenance burden.
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.
Great idea. I've opened #86 to track this.
The legacy interface (arguably) had better support for this, because the user was required to describe all the code in the codebase (via globs) in addition to providing the compile commands. But it still wasn't perfect, because we couldn't identify source files outside of the globs. Actually walking the source directory and alerting the user to anything we find would be much more useful.
Signed-off-by: John Pennycook <[email protected]>
Signed-off-by: John Pennycook <[email protected]>
I've added a README explaining that sphinx and furo are required in ae283fe. |
Related issues
Closes #19.
Proposed changes
Note that the README changes remove the
IMPORTANT
callout about the change incodebasin
behavior. The plan is that we'll include this in the Release Notes instead, so that we can have a clean break for the new documentation.