Merge pull request #4 from useblocks/fix-default-config

🔧Fix default config

Author: juiwenchen

docs/source/basics/local_link.gif

@@ -1,74 +1,54 @@
 Quick Start
 ===========
 
-``CodeLinks`` provides ``src-trace`` directive and it can be used in the following ways:
+.. image:: local_link.gif
 
-.. code-block:: rst
+Three steps to quickly run ``CodeLinks`` to achieve **the above**:
 
-   .. src-trace:: example_with_file
-      :project: project_config
-      :file: example.cpp
+- Configure Sphinx
+- Apply One-line comment for a ``Sphinx-Needs`` need item
+- Use ``src-trace`` directive
 
-or
-
-.. code-block:: rst
-
-   .. src-trace:: example_with_directory
-      :project: project_config
-      :directory: ./example
-
-``src-trace`` directive has the following options:
-
-* **project**: the project config specified in ``conf.py`` or ``toml`` file to be used for source tracing.
-* **file**: the source file to be traced.
-* **directory**: the source files in the directory to be traced recursively.
-
-Regarding the **file** and **directory** options:
-
-- they are optional and mutually exclusive.
-- the given paths are relative to ``src_dir`` defined in the source tracing configuration
-- if not given, the whole project will be examined.
-
-Example
--------
-
-With the following configuration for a demo source code project `dcdc <https://github.com/useblocks/sphinx-codelinks/tree/main/tests/data/dcdc>`_,
+Sphinx Config
+-------------
 
 .. code-block:: python
    :caption: conf.py
 
+   extensions = [
+       'sphinx_needs',
+       'sphinx_codelinks'
+   ]
    src_trace_config_from_toml = "src_trace.toml"
 
 .. literalinclude:: ./../../src_trace.toml
    :caption: src_trace.toml
    :language: toml
+   :lines: 27-29
 
-``src-trace`` directive can be used with **file** option:
+One-line comment
+----------------
 
-.. code-block:: rst
+.. literalinclude:: ./../../../tests/doc_test/minimum_config/dummy_src.cpp
+   :caption: dummy_src.cpp
+   :language: cpp
 
-   .. src-trace:: dcdc demo_1
-      :project: dcdc
-      :file: ./charge/demo_1.cpp
 
-The needs defined in source code are extracted and rendered to:
+Directive
+---------
 
-.. src-trace:: dcdc demo_1
-   :project: dcdc
-   :file: ./charge/demo_1.cpp
+.. literalinclude:: ./../../../tests/doc_test/minimum_config/index.rst
+   :caption: index.rst
+   :language: rst
 
-``src-trace`` directive can be used with **directory** option:
 
-.. code-block:: rst
 
-   .. src-trace:: dcdc charge
-      :project: dcdc
-      :directory: ./discharge
+Example
+-------
 
-The needs defined in source code are extracted and rendered to:
+.. src-trace:: dummy src
+   :project: src
 
-.. src-trace:: dcdc charge
-   :project: dcdc
-   :directory: ./discharge
+.. note:: **local-url** is not working on the website as it only supports local browse
 
-To have a more customized configuration of ``CodeLinks``, please refer to :ref:`configuration <configuration>`.
+Section :ref:`Directive <directive>` provides more adavanced usage.

docs/source/basics/quickstart.rst

@@ -37,9 +37,9 @@ but with the ``src_trace_`` prefix removed.
 src_trace_set_local_url
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Set this option to ``False``, if the local link between a need to the local source code where it is defined is not required.
+Set this option to ``True``, if the local link between a need to the local source code where it is defined is required.
 
-Default: **True**
+Default: **False**
 
 .. tabs::
 
@@ -77,12 +77,12 @@ Default: **local-url**
 src_trace_set_remote_url
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Set this option to ``False``, if the remote link between a need to the remote source code
-where it is defined is not required.
+Set this option to ``True``, if the remote link between a need to the remote source code
+where it is defined is required.
 
 The remote means where the source code is hosted such as GitHub.
 
-Default: **True**
+Default: **False**
 
 .. tabs::
 

docs/source/components/configuration.rst

@@ -0,0 +1,79 @@
+.. _directive:
+
+Directive
+=========
+
+``CodeLinks`` provides ``src-trace`` directive and it can be used in the following ways:
+
+.. code-block:: rst
+
+   .. src-trace:: example_with_file
+      :project: project_config
+      :file: example.cpp
+
+or
+
+.. code-block:: rst
+
+   .. src-trace:: example_with_directory
+      :project: project_config
+      :directory: ./example
+
+``src-trace`` directive has the following options:
+
+* **project**: the project config specified in ``conf.py`` or ``toml`` file to be used for source tracing.
+* **file**: the source file to be traced.
+* **directory**: the source files in the directory to be traced recursively.
+
+Regarding the **file** and **directory** options:
+
+- they are optional and mutually exclusive.
+- the given paths are relative to ``src_dir`` defined in the source tracing configuration
+- if not given, the whole project will be examined.
+
+Example
+-------
+
+With the following configuration for a demo source code project `dcdc <https://github.com/useblocks/sphinx-codelinks/tree/main/tests/data/dcdc>`_,
+
+.. code-block:: python
+   :caption: conf.py
+
+   src_trace_config_from_toml = "src_trace.toml"
+
+.. literalinclude:: ./../../src_trace.toml
+   :caption: src_trace.toml
+   :language: toml
+   :lines: 1-25
+
+``src-trace`` directive can be used with **file** option:
+
+.. code-block:: rst
+
+   .. src-trace:: dcdc demo_1
+      :project: dcdc
+      :file: ./charge/demo_1.cpp
+
+The needs defined in source code are extracted and rendered to:
+
+.. src-trace:: dcdc demo_1
+   :project: dcdc
+   :file: ./charge/demo_1.cpp
+
+``src-trace`` directive can be used with **directory** option:
+
+.. code-block:: rst
+
+   .. src-trace:: dcdc charge
+      :project: dcdc
+      :directory: ./discharge
+
+The needs defined in source code are extracted and rendered to:
+
+.. src-trace:: dcdc charge
+   :project: dcdc
+   :directory: ./discharge
+
+.. note:: **local-url** is not working on the website as it only supports local browse
+
+To have a more customized configuration of ``CodeLinks``, please refer to :ref:`configuration <configuration>`.

docs/source/components/directive.rst

@@ -57,9 +57,11 @@ Contents
    :maxdepth: 1
    :caption: Components
 
+   components/cli
    components/configuration
+   components/directive
    components/oneline
-   components/cli
+
 
 .. toctree::
    :maxdepth: 1

docs/source/index.rst

@@ -7,12 +7,8 @@ remote_url_field = "remote-url" # Need's field name for remote URL
 
 [src_trace.projects.dcdc]
 # Configuration for source tracing project "dcdc"
-comment_type = "cpp"                                                                              # Type of the comment, only support C/C++ for now
 src_dir = "../tests/data/dcdc"                                                                    # Relative path from conf.py to the source directory
 remote_url_pattern = "https://github.com/useblocks/sphinx-codelinks/blob/{commit}/{path}#L{line}" # URL pattern for remote source code
-exclude = ["dcdc/src/ubt/ubt.cpp"]                                                                # Exclude files from source tracing
-include = ["**/*.cpp", "**/*.hpp"]                                                                # Include files for source tracing
-gitignore = true                                                                                  # Respect .gitignore to filter files
 
 [src_trace.projects.dcdc.oneline_comment_style]
 # Configuration for oneline comment style
@@ -27,3 +23,7 @@ needs_fields = [
   { "name" = "links", "type" = "list[str]", "default" = [
   ] },
 ]
+
+[src_trace.projects.src]
+src_dir = "../tests/doc_test/minimum_config"
+remote_url_pattern = "https://github.com/useblocks/sphinx-codelinks/blob/{commit}/{path}#L{line}"

docs/src_trace.toml

@@ -26,7 +26,7 @@
 
 @app.command(no_args_is_help=True)
 def discover(
-    root_dir: Annotated[
+    src_dir: Annotated[
         Path,
         typer.Argument(
             ...,
@@ -68,7 +68,7 @@ def discover(
     from sphinx_codelinks.source_discovery.source_discover import SourceDiscover
 
     source_discover = SourceDiscover(
-        root_dir=root_dir,
+        src_dir=src_dir,
         exclude=exclude,
         include=include,
         file_types=file_types,
@@ -134,8 +134,8 @@ def vdoc(
     if oneline_errors:
         errors.appendleft("Invalid oneline comment style configuration:")
         errors.extend(oneline_errors)
-
-    src_discovery_dict, src_discovery_errors = build_src_discovery_dict(project_config)
+    src_discovery_errors = []
+    src_discovery_dict = build_src_discovery_dict(project_config)
     if src_discovery_dict:
         src_discovery_config = SourceDiscoveryConfig(**src_discovery_dict)
     else:
@@ -151,9 +151,9 @@ def vdoc(
 
     from sphinx_codelinks.source_discovery.source_discover import SourceDiscover
 
-    src_root_dir = (config.parent / src_discovery_config.root_dir).resolve()
+    src_dir = (config.parent / src_discovery_config.src_dir).resolve()
     source_discover = SourceDiscover(
-        root_dir=src_root_dir,
+        src_dir=src_dir,
         exclude=src_discovery_config.exclude,
         include=src_discovery_config.include,
         file_types=src_discovery_config.file_types,
@@ -164,7 +164,7 @@ def vdoc(
 
     virtual_docs = VirtualDocs(
         src_files=source_discover.source_paths,
-        src_dir=str(src_root_dir),
+        src_dir=str(src_dir),
         output_dir=str(output_dir),
         oneline_comment_style=oneline_comment_style,
         comment_type=src_discovery_config.file_types[0]
@@ -178,7 +178,7 @@ def vdoc(
         typer.echo("The virtual documents are generated:")
         for v_doc in virtual_docs.virtual_docs:
             json_path = output_dir / v_doc.filepath.with_suffix(".json").relative_to(
-                src_root_dir
+                src_dir
             )
             typer.echo(json_path)
     else:

src/sphinx_codelinks/cmd.py

@@ -6,7 +6,7 @@
 
 
 class SourceDiscoveryConfigType(TypedDict, total=False):
-    root_dir: Path
+    src_dir: Path
     exclude: list[str]
     include: list[str]
     gitignore: bool
@@ -19,8 +19,8 @@ class SourceDiscoveryConfig:
     def field_names(cls) -> set[str]:
         return {item.name for item in fields(cls)}
 
-    root_dir: Path = field(
-        default_factory=lambda: Path.cwd(), metadata={"schema": {"type": "string"}}
+    src_dir: Path = field(
+        default_factory=lambda: Path("./"), metadata={"schema": {"type": "string"}}
     )
     """The root of the source directory."""
 
@@ -41,7 +41,9 @@ def field_names(cls) -> set[str]:
 
     file_types: list[str] = field(
         default_factory=lambda: ["c", "h", "cpp", "hpp"],
-        metadata={"schema": {"type": "array", "items": {"type": "string"}}},
+        metadata={
+            "schema": {"type": "array", "items": {"enum": ["c", "h", "cpp", "hpp"]}}
+        },
     )
     """The file types to discover."""
 

src/sphinx_codelinks/source_discovery/config.py

@@ -9,13 +9,13 @@
 class SourceDiscover:
     def __init__(
         self,
-        root_dir: Path,
+        src_dir: Path,
         exclude: list[str] | None = None,
         include: list[str] | None = None,
         gitignore: bool = True,
         file_types: list[str] | None = None,
     ):
-        self.root_path = root_dir
+        self.root_path = src_dir
         self.exclude = exclude
         self.include = include
         # Only gitignore at source root is considered.