🤖 Improve documentation

🤖 Fix documentation typos in manifest reference

🤖 Fix inconsistent field naming: use 'index' instead of 'registry'

🤖 Add comprehensive documentation for the 'flist' field

Added detailed documentation for the previously undocumented 'flist' field in the
[package] section of the manifest format reference:

- Added 'flist' to the field list in the overview

🤖 Add validation to reject empty package names

Added field validator to Package class to reject empty and whitespace-only
package names. This improves validation and prevents invalid manifests.

🤖 Clarify that the 'description' field is optional

🤖 Fix authors field documentation

Updated the authors field documentation to reflect all accepted formats:
- Single string with optional email
- List of strings
- Dictionary with name and email

🤖 Clarify optional dependencies format equivalence

Author: Ben Davis

docs/source/manifest_reference/manifest_format.rst

@@ -4,7 +4,7 @@ The Manifest Format
 ===================
 
 The `proj.toml` file within a package is called its *manifest* file.
-It is generally written i8n the `TOML <https://toml.io>`__ format.
+It is generally written in the `TOML <https://toml.io>`__ format.
 Specifically, it currently supports `TOML v1.0.0 <https://toml.io/en/v1.0.0>`__.
 It contains the metadata needed for inclusion of the package into a HDL/RTL project.
 
@@ -14,13 +14,14 @@ Every manifest contains some of the following:
 
   - :ref:`name <name_field>` - The name of the package
   - :ref:`version <version_field>` - The version of the package
-  - :ref:`description <description_field>` - The description of the package
-  - :ref:`authors <authors_field>` - The authors of the package
+  - :ref:`description <description_field>` - (Optional) The description of the package
+  - :ref:`authors <authors_field>` - (Optional) The authors of the package
   - :ref:`readme <readme_field>` - The readme of the package
+  - :ref:`flist <flist_field>` - The file list of the package
 
 - :ref:`[dependencies] <dependencies_section>`
 - :ref:`[optional_dependencies] <optional_dependencies_section>`
-- :ref:`[regsistries] <registries_section>`
+- :ref:`[registries] <registries_section>`
 
 
 .. _package_section:
@@ -38,6 +39,9 @@ The ``name`` field
 The package name is a unique identifier used to refer to the package.
 It is used when listed as a dependency in other manifests and as the default inferred name for certain other fields.
 
+The name field is required and must be a non-empty string.
+Empty strings and whitespace-only strings are not allowed and will result in a validation error.
+
 
 .. _version_field:
 
@@ -57,21 +61,69 @@ The ``description`` field
 The ``description`` is a short summary of the package.
 This field is treated as a plain-text string.
 
+This field is optional.
+If not specified, it defaults to an empty string.
+However, providing a description is strongly recommended as it helps users understand the purpose and functionality of the package.
+
+Example TOML with description:
+
+.. code-block:: TOML
+
+    [package]
+    name = "my-package"
+    version = "1.0.0"
+    description = "A package for HDL design and verification"
+
+Example TOML without description (uses default empty string):
+
+.. code-block:: TOML
+
+    [package]
+    name = "my-package"
+    version = "1.0.0"
+
 
 .. _authors_field:
 
 The ``authors`` field
 ^^^^^^^^^^^^^^^^^^^^^^
 
-The ``authors`` of the package.
-This field is optional.
-If not specified, it defaults to not including any author information.
-This field can either be an array of strings, or an array of dictionaries.
+The ``authors`` field specifies the authors of the package.
+This field is optional. If not specified, no author information is included.
+
+The ``authors`` field accepts several formats:
 
-If the ``authors`` field is an array of strings, it is treated as a list.
-It is permissible to include the authors email within angled brackets at the end of the authors string.
+**Single string** (with optional email in angle brackets):
 
-If the ``authors`` field is an array of dictionaries, it is treated as a list of authors where the valid keys are ``name`` and ``email``.
+.. code-block:: TOML
+
+     [package]
+     authors = "John Doe"
+     
+     # Or with email:
+     authors = "John Doe <john.doe@example.com>"
+
+**List of strings**:
+
+.. code-block:: TOML
+
+     [package]
+     authors = [
+         "John Doe <john.doe@example.com>",
+         "Jane Smith <jane.smith@example.com>"
+     ]
+
+**Dictionary with name and email**:
+
+.. code-block:: TOML
+
+     [package]
+     authors = {name = "John Doe", email = "john.doe@example.com"}
+     
+     # Email is optional:
+     authors = {name = "John Doe"}
+
+Choose the format that best suits your needs. For multiple authors, the list format is most readable.
 
 
 .. _readme_field:
@@ -85,6 +137,42 @@ If not specified, it defaults to not including any readme information.
 This field is relative to the location of the manifest file.
 
 
+.. _flist_field:
+
+The ``flist`` field
+^^^^^^^^^^^^^^^^^^^
+
+The ``flist`` field points to the relative location of the file list for the package.
+A file list contains the paths to all source files that should be included when this package is used as a dependency in another project.
+
+This field is optional.
+If not specified, it defaults to ``<package-name>.f`` in the same directory as the manifest file.
+For example, if the package name is ``my-package``, the default file list would be ``my-package.f``.
+This field is relative to the location of the manifest file.
+
+Example TOML with explicit file list:
+
+.. code-block:: TOML
+
+    [package]
+    name = "my-package"
+    version = "1.0.0"
+    description = "A sample package"
+    flist = "rtl/sources.f"
+
+Example TOML using the default file list (``my-package.f``):
+
+.. code-block:: TOML
+
+    [package]
+    name = "my-package"
+    version = "1.0.0"
+    description = "A sample package"
+
+When a ``fastsandpm`` compatible package is used as a dependency, the specified file list is automatically included in the dependent project.
+For projects that do not specify an ``flist`` field, FastSandPM will look for a file named ``<package-name>.f`` at the root of the dependency directory.
+
+
 .. _dependencies_section:
 
 The ``[dependencies]`` section
@@ -100,9 +188,9 @@ The dependencies section contains a group of :ref:`dependency specifiers <specif
 These are always brought in to the project.
 Additionally, if these point to projects with a ``fastsandpm`` manifest, their dependencies will also be brought in.
 
-Once the dpendencies are resolved a filelist will be created.
-For ``fastsandpm`` compatible projects these will be included by pointing to the ``filelist`` field of the ``[package]`` section.
-Any other project will point to a filelist at the top of the dependency's directory with the same name as the dependency.
+Once the dependencies are resolved a file list will be created.
+For ``fastsandpm`` compatible projects, the file list is automatically included by pointing to the :ref:`flist <flist_field>` field of the ``[package]`` section.
+Any other project will use a file list located at the top of the dependency's directory with the same name as the dependency.
 
 For example:
 
@@ -128,31 +216,61 @@ For example:
 
 .. code-block:: TOML
 
-    [optional_dependencies]
+     [optional_dependencies]
 
-    uvm = [
-        {name="uvm_utils", version="^1.0.0"},
-        {name="improved_uvm_ral", version=">0.1.0", git="DCC_UVM"},
-    ]
+     uvm = [
+         {name="uvm_utils", version="^1.0.0"},
+         {name="improved_uvm_ral", version=">0.1.0", git="DCC_UVM"},
+     ]
 
 The above creates a UVM dependency group that contains the ``uvm_utils`` and ``improved_uvm_ral`` packages.
 
 An alternative but equally valid way to write this TOML would be:
 
 .. code-block:: TOML
 
-    [optional_dependencies.uvm]
+     [optional_dependencies.uvm]
 
-    uvm_utils = "^1.0.0"
-    improved_uvm_ral = {version=">0.1.0", git="DCC_UVM"}
+     uvm_utils = "^1.0.0"
+     improved_uvm_ral = {version=">0.1.0", git="DCC_UVM"}
+
+
+Format Equivalence
+^^^^^^^^^^^^^^^^^^
+
+The two formats shown above are completely equivalent. Both create the same dependency group structure.
+Choose the format that is most readable for your use case:
+
+- **List format** (``[optional_dependencies]`` with array): Better when copying dependency specifications or when dependencies have complex configurations
+- **Table format** (``[optional_dependencies.group]``): More concise and readable for simple version specifications
+
+The following two specifications are identical:
+
+.. code-block:: TOML
+
+     # List format
+     [optional_dependencies]
+     dev = [
+         {name = "pytest", version = "^7.0.0"},
+         {name = "mypy", version = "^1.0.0"}
+     ]
+
+.. code-block:: TOML
+
+     # Table format (recommended for simple cases)
+     [optional_dependencies.dev]
+     pytest = "^7.0.0"
+     mypy = "^1.0.0"
+
+Choose whichever format makes your manifest more readable and maintainable for your project's needs.
 
 
 .. _registries_section:
 
-The ``[registeries]`` section
+The ``[registries]`` section
 -----------------------------
 
-Additional registeries can be specified in the ``[registries]`` section.
-A regsitry type exists for each :ref:`dependency specifier <specifying_dependencies>` type.
+Additional registries can be specified in the ``[registries]`` section.
+A registry type exists for each :ref:`dependency specifier <specifying_dependencies>` type.
 
 

docs/source/manifest_reference/specifying_dependencies.rst

@@ -31,21 +31,21 @@ For example you can specify a dependency named ``time`` and version ``1.0.0`` as
     time = "1.0.0"
 
 The version string is a known as a :ref:`version specifier <version_specifier>`.
-These specifiers can be used to set a range of valid versions used for resolving dpendencies.
+These specifiers can be used to set a range of valid versions used for resolving dependencies.
 
 
 Dependencies from Other Registries
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 It is also possible to point to a different index using the ``index`` key in the dependency.
-For example you can specify a dependency named ``time`` and version ``1.0.0`` as follows:
+For example you can specify a dependency named ``time`` and version ``1.0.0`` from a custom registry as follows:
 
 .. code-block:: TOML
 
     [dependencies]
-    time = {registry = "my-registry", version = "1.0.0"}
+    time = {index = "my-registry", version = "1.0.0"}
 
-The value of ``registry`` points to a regsiter definition from the ``[registries]`` section. of the manifest.
+The value of ``index`` points to a registry definition from the ``[registries]`` section of the manifest.
 See the :ref:`registries section documentation <registries_section>` for more information.
 
 
@@ -77,7 +77,7 @@ By default the upstream default branch will be used.
 .. note::
 
    If when the dependencies are updated the existing local copy is dirty an error will be raised.
-   A user of the library can force the update by setting the ``force_update`` flag to ``true`` or ignore the error by settign ``ignore_dirty`` to ``true``.
+   A user of the library can force the update by setting the ``force_update`` flag to ``true`` or ignore the error by setting ``ignore_dirty`` to ``true``.
 
 
 Git Commit & Tag Specifiers

src/fastsandpm/manifest.py

@@ -58,6 +58,7 @@
     RootModel,
     ValidationError,
     WithJsonSchema,
+    field_validator,
     model_validator,
 )
 
@@ -140,6 +141,24 @@ class Package(BaseModel):
     readme: pathlib.Path | None = None  # TODO: Field(default_factory=_find_readme)
     """Path to the README file relative to manifest."""
 
+    @field_validator("name")
+    @classmethod
+    def validate_name_not_empty(cls, v: str) -> str:
+        """Validate that package name is not empty.
+
+        Args:
+            v: The package name to validate.
+
+        Returns:
+            The validated package name.
+
+        Raises:
+            ValueError: If the name is empty or contains only whitespace.
+        """
+        if not v or not v.strip():
+            raise ValueError("Package name cannot be empty or whitespace-only")
+        return v
+
 
 class Dependencies(RootModel[list[ConcreteRequirement]]):
     """A collection of package dependencies.

tests/manifest/test_manifest_package.py

@@ -62,13 +62,17 @@ def test_name_with_numbers(self) -> None:
         package = Package(name="package123", version="1.0.0", description="A test package")
         assert package.name == "package123"
 
-    def test_name_accepts_empty_string(self) -> None:
-        """Test that name currently accepts an empty string.
+    def test_name_rejects_empty_string(self) -> None:
+        """Test that name field rejects empty strings."""
+        with pytest.raises(ValidationError) as exc_info:
+            Package(name="", version="1.0.0", description="A test package")
+        assert "cannot be empty" in str(exc_info.value).lower()
 
-        Note: This documents current behavior. Future validation may reject empty names.
-        """
-        package = Package(name="", version="1.0.0", description="A test package")
-        assert package.name == ""
+    def test_name_rejects_whitespace_only(self) -> None:
+        """Test that name field rejects whitespace-only strings."""
+        with pytest.raises(ValidationError) as exc_info:
+            Package(name="   ", version="1.0.0", description="A test package")
+        assert "cannot be empty" in str(exc_info.value).lower()
 
 
 class TestPackageVersion: