Add the supported targets page #88

Miauwkeru · 2025-07-29T14:48:17Z

Add supported targets page with an extension
Add the defaults for every type
Remove unnecessary spaces from files
Let autoapi also discover all _os.py modules

closes #84

Miauwkeru · 2025-07-29T14:51:38Z

When testing against autoapi, I did notice that a few projects fail when generating the api documentation. These are:

dissect.cstruct
flow.record
dissect.target (because of the added support for _os modules in Let autoapi discover all _os.py modules #89 )
dissect.qnfx
dissect.shellitem

I'll make a ticket for those projects

Miauwkeru · 2025-07-29T14:59:46Z

How the table generation works. We have some default csv files that contain the descriptions.
for example _defaults/filesystems.csv contains the descriptions for all the different filesystems.

the _ext/supported_targets.py extension maps those descriptions together with all the filesystems it can find (within dissect.target.filesystems) and generates a csv file inside the supported_targets/ directory . (e.g. supported_targets/filesystems.csv ). If a description is missing for a specific filesystem it will generate a warning containing information on how to resolve it.

The output format depends on the type of file being generated (loaders looks different from filesystem for example), but it comes down to:

Class, ..., Description
:class:`link.to.filesystem.Filesystem`, ..., "Description for the filsystem"

the supported-targets.rst file uses a csv-table to read the generated csv file.

Schamper

Note that the original ticket did warn that an automated approach might be hard and not lead to a high enough quality result. If you do still intend to attempt to do it in an automated fashion, it must be better and lead to as high a quality result as a handcrafted table.

Schamper · 2025-08-20T08:56:00Z

docs/source/_ext/supported_targets.py

+    return [loader.realattr for loader in LOADERS_BY_SCHEME.values()]
+
+
+SUPPORTED_SYSTEMS = [


Why is this so complex? What's wrong with just iterating i.e. loader.LOADERS?

Besides, it's giving a wrong impression on things that are supported. Not everything that's in dissect/target/filesystems is actually supported or should be listed here. Who cares about ITunesFilesystem if it can't actually be manually opened or selected? What value is there in knowing that it exists? I do care about the ITunes Backup loader (not ITunesLoader, what's that?).

This page should reflect what a user can expect from Dissect, not a factual representation of what modules and classes exist. I open the API documentation if I was looking for that.

Schamper · 2025-08-20T09:00:24Z

docs/source/supported-targets.rst

+.. Descriptions can be reworded by changing _defaults/loaders.csv
+.. csv-table:: Supported Loaders
+   :header-rows: 1
+   :file: /supported_targets/loaders.csv
+   :widths: 15 10 25


The CSV approach sucks a bit, is there not a better way? Maybe a custom table directive where you can manually override entries, keyed on the module name?

I thought a bit further about it, and having a plugin automatically generate it will be more effort than it is worth. So I opted to write it manually

The contents get generated from the files inside of defaults_/*.csv

These were generated by taking the first line from the class its docstring

Schamper

In general, remember that this page should not have too much implementation details. Someone reading this should not have to know what a plugin is. Any and all links or references to more in-depth or API stuff should be optional links, and not part of the main text.

Also, maybe vibe some sentences to make them flow nicer.

Schamper · 2025-10-09T11:52:43Z

docs/source/index.rst

    Shell </target-shell>
    Mount </target-mount>
    Acquire </acquire>
+    Supported Targets </supported-targets>


Maybe put this just above tutorial?

Schamper · 2025-10-09T11:53:12Z

docs/source/index.rst

Not a change in this PR, but why does this page like to dissect.target and not dissect? And "github" is not even properly capitalized...

Get in touch, join us on github <https://github.com/fox-it/dissect.target>_!

Good question

.gitignore

docs/source/supported-targets.rst

Schamper · 2025-10-09T12:19:13Z

docs/source/supported-targets.rst

+~~~~~~~~~~~~~~~~~
+
+
+Dissect includes a range of ``OSPlugins`` that help identify the operating system present on a target.


Suggested change

Dissect includes a range of ``OSPlugins`` that help identify the operating system present on a target.

Dissect includes a range of ``OSPlugins`` that help identify the operating system present on a target.

Unnecessary detail? Just say we support various operating systems.

Schamper · 2025-10-09T12:19:56Z

docs/source/supported-targets.rst

+   :header-rows: 1
+   :widths: 20
+
+   * - Operating System


There's some improper capitalization in this list.

Schamper · 2025-10-09T12:20:35Z

docs/source/supported-targets.rst

+   :widths: 20
+
+   * - Operating System
+   * - :class:`Android <dissect.target.plugins.os.unix.linux.android._os.AndroidPlugin>`


Maybe don't list this alphabetically, but rather sorted by inheritance.

I'll sort it by inheritance

Schamper · 2025-10-09T12:21:09Z

docs/source/supported-targets.rst

+   * - Child Target
+     - Description
+   * - :class:`Colima <dissect.target.plugins.child.colima.ColimaChildTargetPlugin>`
+     - Child target plugin that yields Colima containers.


Suggested change

- Child target plugin that yields Colima containers.

- Colima containers.

This prefix is unnecessary. And what is Colima? Just add one line for everything.

Co-authored-by: Erik Schamper <[email protected]>

Miauwkeru requested a review from Schamper July 29, 2025 14:48

Miauwkeru force-pushed the supported-targets branch from 38dd213 to 981e014 Compare July 30, 2025 11:35

Schamper requested changes Aug 20, 2025

View reviewed changes

Miauwkeru added 2 commits October 6, 2025 14:12

Add supported targets page with an extension

b80f095

The contents get generated from the files inside of defaults_/*.csv

Add the defaults for every type

b709f12

These were generated by taking the first line from the class its docstring

Miauwkeru marked this pull request as draft October 8, 2025 15:28

Miauwkeru force-pushed the supported-targets branch from 981e014 to 3e3f6f4 Compare October 8, 2025 15:35

Miauwkeru added 3 commits October 8, 2025 17:39

Remove supported_targets plugin in favor of a manual table

3134ef0

Add manual list of supported targets

b9b65f5

Ignore generated plugins

3d50ee3

Miauwkeru force-pushed the supported-targets branch from 3e3f6f4 to 3d50ee3 Compare October 8, 2025 15:39

Cleanup document

08b2d96

Schamper requested changes Oct 9, 2025

View reviewed changes

Apply suggestions from code review

763ee09

Co-authored-by: Erik Schamper <[email protected]>

		return [loader.realattr for loader in LOADERS_BY_SCHEME.values()]


		SUPPORTED_SYSTEMS = [

		~~~~~~~~~~~~~~~~~


		Dissect includes a range of ``OSPlugins`` that help identify the operating system present on a target.

	- Child target plugin that yields Colima containers.
	- Colima containers.

Add the supported targets page #88

Are you sure you want to change the base?

Add the supported targets page #88

Uh oh!

Conversation

Miauwkeru commented Jul 29, 2025

Uh oh!

Miauwkeru commented Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Miauwkeru commented Jul 29, 2025

Uh oh!

Schamper left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Schamper left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Miauwkeru commented Jul 29, 2025 •

edited

Loading