Fix Sphinx docs warnings (#116)

Author: JSCU-CNI

.gitattributes

@@ -0,0 +1 @@
+tests/_data/** filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -6,6 +6,6 @@ dist/
 *.pyc
 __pycache__/
 .pytest_cache/
-tests/docs/api
-tests/docs/build
+tests/_docs/api
+tests/_docs/build
 .tox/

dissect/cstruct/types/enum.py

@@ -114,13 +114,13 @@ class Enum(BaseType, IntEnum, metaclass=EnumMetaType):
     Enums can be made using any integer type.
 
     Example:
-        When using the default C-style parser, the following syntax is supported:
+        When using the default C-style parser, the following syntax is supported::
 
             enum <name> [: <type>] {
                 <values>
             };
 
-        For example, an enum that has A=1, B=5 and C=6 could be written like so:
+        For example, an enum that has A=1, B=5 and C=6 could be written like so::
 
             enum Test : uint16 {
                 A, B=5, C

dissect/cstruct/types/flag.py

@@ -15,13 +15,13 @@ class Flag(BaseType, IntFlag, metaclass=EnumMetaType):
     Flags can be made using any integer type.
 
     Example:
-        When using the default C-style parser, the following syntax is supported:
+        When using the default C-style parser, the following syntax is supported::
 
             flag <name> [: <type>] {
                 <values>
             };
 
-        For example, a flag that has A=1, B=4 and C=8 could be written like so:
+        For example, a flag that has A=1, B=4 and C=8 could be written like so::
 
             flag Test : uint16 {
                 A, B=4, C

tests/_data/testdef.txt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:46fab39cf8ed080513ea9e193ba08174f0133e133d249e60e5d819eb396ec7a7
+size 32

tests/docs/Makefile tests/_docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?= -jauto
+SPHINXOPTS    ?= -jauto -w $(BUILDDIR)/warnings.log --fail-on-warning
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = build

tests/_docs/__init__.py

@@ -1,3 +1,5 @@
+project = "dissect.cstruct"
+
 extensions = [
     "autoapi.extension",
     "sphinx.ext.autodoc",
@@ -32,3 +34,9 @@
 autodoc_member_order = "groupwise"
 
 autosectionlabel_prefix_document = True
+
+suppress_warnings = [
+    # https://github.com/readthedocs/sphinx-autoapi/issues/285
+    "autoapi.python_import_resolution",
+    "ref.python",
+]

tests/docs/conf.py tests/_docs/conf.py

@@ -28,7 +28,7 @@ def test_duplicate_type(cs: cstruct, compiled: bool) -> None:
 
 
 def test_load_file(cs: cstruct, compiled: bool) -> None:
-    path = Path(__file__).parent / "data/testdef.txt"
+    path = Path(__file__).parent / "_data/testdef.txt"
 
     cs.loadfile(path, compiled=compiled)
     assert "test" in cs.typedefs

tests/docs/index.rst tests/_docs/index.rst

@@ -54,12 +54,12 @@ deps =
     sphinx-design
     furo
 commands =
-    make -C tests/docs clean
-    make -C tests/docs html
+    make -C tests/_docs clean
+    make -C tests/_docs html
 
 [testenv:docs-linkcheck]
 allowlist_externals = make
 deps = {[testenv:docs-build]deps}
 commands =
-    make -C tests/docs clean
-    make -C tests/docs linkcheck
+    make -C tests/_docs clean
+    make -C tests/_docs linkcheck