Docs/improve docstrings

README.md

@@ -1,8 +1,50 @@
 # FastSandPM
-A package management and dependency resolution tool for HDL Design and DV projects
+An RTL Design and DV package manager for python tools. Manage your RTL and
+design verification library dependencies by cloning, updating, and
+version-controlling git repositories.
 
 [![Tests](https://github.com/RISCY-Lib/fastsandpm/actions/workflows/run-ci-tests.yml/badge.svg)](https://github.com/RISCY-Lib/fastsandpm/actions/workflows/run-ci-tests.yml)
 [![PyPI Latest Release](https://img.shields.io/pypi/v/fastsandpm.svg)](https://pypi.org/project/fastsandpm/)
 [![docs](https://readthedocs.org/projects/fastsandpm/badge)](https://fastsandpm.readthedocs.io/en/latest/index.html)
 
 See [Read-The-Docs](https://fastsandpm.readthedocs.io/en/latest/index.html) for details
+
+Key Features
+------------
+
+- **Library Management**: Clone and update RTL/DV libraries from git repositories
+- **Version Pinning**: Pin libraries to specific tags, branches, or commits
+- **Version Ranges**: Specify flexible version constraints (e.g., ``>=1.0.0,<2.0.0``)
+- **TOML Configuration**: Organize libraries in configuration files with sub-headings
+- **Local Development**: Symlink local directories for development workflows
+- **Multi-Remote Support**: Automatically discover repositories across configured remotes
+
+Quick Start
+-----------
+
+Installation:
+
+.. code-block:: bash
+
+   # For UV Based projects
+   uv add fastsandpm
+
+   # For pip-based projects
+   pip install fastsandpm
+
+Basic Usage:
+
+    >>> import pathlib
+    >>> import fastsandpm
+    >>> manifest = fastsandpm.get_manifest("./my-project")
+    >>> print(manifest.package.name)
+    'my-package'
+    >>> resolved = fastsandpm.dependencies.resolve(manifest)
+    >>> print(type(resolved))
+    <class 'dict'>
+    >>> build_library(resolved, pathlib.Path("my-library"))
+
+This will bring in the library dependencies for a project into the specified directory.
+Additionally, a 'dependencies.f' file will be created which will point to the dependencies file list in the required order.
+
+For more examples, see [the docs](https://fastsandpm.readthedocs.io/en/latest/usage_guide/index.html) for details.

docs/source/index.rst

@@ -1,6 +1,7 @@
 .. fastsandpm documentation master file
 
 fastsandpm Documentation
+
 ===========================================
 
 An RTL Design and DV package manager for python tools. Manage your RTL and
@@ -32,19 +33,15 @@ Installation:
 
 Basic Usage:
 
-.. code-block:: python
-
-   import pathlib
-   import fastsandpm
-
-   # Get the manifest of the current project
-   manifest = fastsandpm.get_manifest(pathlib.Path("some/repo/path"))
-
-   # Resolve the libraries
-   deps = fastsandpm.resolve_dependencies(manifest.dependencies, manifest.optional_dependencies["dev"])
-
-   # Update the libraries
-   fastsandpm.update_deps(libraries, pathlib.Path("some/library/.path"))
+    >>> import pathlib
+    >>> import fastsandpm
+    >>> manifest = fastsandpm.get_manifest("./my-project")
+    >>> print(manifest.package.name)
+    'my-package'
+    >>> resolved = fastsandpm.dependencies.resolve(manifest)
+    >>> print(type(resolved))
+    <class 'dict'>
+    >>> build_library(resolved, pathlib.Path("my-library"))
 
 This will bring in the library dependencies for a project into the specified directory.
 Additionally, a 'dependencies.f' file will be created which will point to the dependencies file list in the required order.

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

docs/source/usage_guide/index.rst

@@ -23,4 +23,6 @@ Or with pip:
 Basic Usage
 -----------
 
+.. NOTE::
 
+   TODO: Work in progress