Merge pull request #24 from ycexiao/init-doc

sbillinge · web-flow · commit d2324b4c1d1c · 2026-02-04T21:50:52.000-08:00
docs: initialize the documentation
diff --git a/docs/source/api/pdfbl.sequential.example_package.rst b/docs/source/api/pdfbl.sequential.example_package.rst
diff --git a/docs/source/api/pdfbl.sequential.rst b/docs/source/api/pdfbl.sequential.rst
@@ -10,21 +10,25 @@
     :undoc-members:
     :show-inheritance:
 
-Subpackages
------------
-
-.. toctree::
-   pdfbl.sequential.example_package
 
 Submodules
 ----------
 
-|module|
---------
+pdfbl.sequential.pdfadapter module
+----------------------------------
+
+.. automodule:: pdfbl.sequential.pdfadapter
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    :no-index:
+
 
-.. |module| replace:: pdfbl.sequential.example_submodule module
+pdfbl.sequential.sequential_cmi_runner module
+---------------------------------------------
 
-.. automodule:: pdfbl.sequential.example_submodule
+.. automodule:: pdfbl.sequential.sequential_cmi_runner
     :members:
     :undoc-members:
     :show-inheritance:
+    :no-index:
diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
@@ -8,72 +8,5 @@
 Getting started
 ================
 
-Here are some example templates provided to help you get started with writing your documentation. You can use these templates to create your own documentation.
-
-Reuse ``.rst`` files across multiple pages
-------------------------------------------
-
-Here is how you can reuse a reusable block of ``.rst`` files across multiple pages:
-
-.. include:: snippets/example-table.rst
-
-.. warning::
-
-    Ensure that the ``.rst`` file you are including is not too long. If it is too long, it may be better to split it into multiple files and include them separately.
-
-Refer to a specific section in the documentation
-------------------------------------------------
-
-You can use the ``ref`` tag to refer to a specific section in the documentation. For example, you can refer to the section below using the ``:ref:`` tag as shown :ref:`here <attach-image>`.
-
-.. note::
-
-    Please check the raw ``.rst`` file of this page to see the exact use of the ``:ref:`` tag.
-
-Embed your code snippets in the documentation
----------------------------------------------
-
-Here is how you can write a block of code in the documentation. You can use the ``code-block`` directive to write a block of code in the documentation. For example, you can write a block of code as shown below:
-
-.. code-block:: bash
-
-    # Create a new environment, without build dependencies (pure Python package)
-    conda create -n <package_name>-env python=3.13 \
-        --file requirements/tests.txt \
-        --file requirements/conda.txt
-
-    # Create a new environment, with build dependencies (non-pure Python package)
-    conda create -n <package_name>-env python=3.13 \
-        --file requirements/tests.txt \
-        --file requirements/conda.txt \
-        --file requirements/build.txt
-
-    # Activate the environment
-    conda activate <package_name>_env
-
-    # Install your package locally
-    # `--no-deps` to NOT install packages again from `requirements.pip.txt`
-    pip install -e . --no-deps
-
-    # Run pytest locally
-    pytest
-
-    # ... run example tutorials
-
-.. _attach-image:
-
-Attach an image to the documentation
-------------------------------------
-
-Here is how you attach an image to the documentation. The ``/docs/source/img/scikit-package-logo-text.png`` example image is provided in the template.
-
-.. image:: ./img/scikit-package-logo-text.png
-    :alt: codecov-in-pr-comment
-    :width: 400px
-    :align: center
-
-
-Other useful directives
------------------------
-
-Here is how you can do menu selection  :menuselection:`Admin --> Settings` and display labels for buttons like :guilabel:`Privacy level`.
+Welcome to the ``pdfbl.sequential`` documentation! Please see our GitHub page
+`here <https://github.com/PDF-bl/pdfbl.sequential>`_ for more information.
diff --git a/docs/source/snippets/example-table.rst b/docs/source/snippets/example-table.rst
diff --git a/news/init-doc.rst b/news/init-doc.rst
@@ -0,0 +1,23 @@
+**Added:**
+
+* No news added: Initialize the documentation.
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* <news item>
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>
diff --git a/src/pdfbl/sequential/pdfadapter.py b/src/pdfbl/sequential/pdfadapter.py
@@ -28,27 +28,26 @@ class PDFAdapter:
 
     Methods
     -------
-    init_profile(profile_path, qmin=None, qmax=None, xmin=None, xmax=None,
-            dx=None)
+    init_profile(profile_path, qmin=None, qmax=None, xmin=None, xmax=None, dx=None)
         Load and initialize the PDF profile from the given file path with
         some optional parameters.
-    init_structures(structure_paths, run_parallel=True)
+    init_structures(structure_paths : list[str], run_parallel=True)
         Load and initialize the structures from the given file paths, and
         generate corresponding PDFGenerator objects.
     init_contribution(equation_string=None)
         Initialize the FitContribution object combining the PDF generators and
         the profile.
     init_recipe()
         Initialize the FitRecipe object for the fitting process.
-    set_initial_variable_values(variable_name_to_value)
+    set_initial_variable_values(variable_name_to_value : dict)
         Update parameter values from the provided dictionary.
-    refine_variables(variable_names)
+    refine_variables(variable_names: list[str])
         Refine the parameters specified in the list and in that order.
     get_variable_names()
         Get the names of all variables in the recipe.
-    save_results(mode="str", filename=None)
+    save_results(mode: str, filename: str=None)
         Save the fitting results.
-    """
+    """  # noqa: E501
 
     def __init__(self):
         pass
@@ -73,16 +72,21 @@ def init_profile(
         ----------
         profile_path : str
             The path to the experimental PDF profile file.
-        qmin : float, optional
-            The minimum Q value for PDF calculation. Default is None.
-        qmax : float, optional
-            The maximum Q value for PDF calculation. Default is None.
-        xmin : float, optional
-            The minimum r value for PDF calculation. Default is None.
-        xmax : float, optional
-            The maximum r value for PDF calculation. Default is None.
-        dx : float, optional
-            The r step size for PDF calculation. Default is None.
+        qmin : float
+            The minimum Q value for PDF calculation. The default value is
+            the one parsed from the profile file.
+        qmax : float
+            The maximum Q value for PDF calculation. The default value is the
+            one parsed from the profile file.
+        xmin : float
+            The minimum r value for PDF calculation. The default value is the
+            one parsed from the profile file.
+        xmax : float
+            The maximum r value for PDF calculation. The default value is the
+            one parsed from the profile file.
+        dx : float
+            The r step size for PDF calculation. The default value is the
+            one parsed from the profile file.
         """
         profile = Profile()
         parser = PDFParser()
@@ -113,9 +117,9 @@ def init_structures(self, structure_paths: list[str], run_parallel=True):
         Notes
         -----
         Planned features:
-        - Support cif file manipulation.
-            - Add/Remove atoms.
-            - symmetry operations?
+            - Support cif file manipulation.
+                - Add/Remove atoms.
+                - symmetry operations?
         """
         if isinstance(structure_paths, str):
             structure_paths = [structure_paths]
@@ -171,14 +175,19 @@ def init_contribution(self, equation_string=None):
 
         Parameters
         ----------
-        equation_string : str, optional
-            The equation string defining the contribution. If None, a default
+        equation_string : str
+            The equation string defining the contribution. The default
             equation will be generated based on the number of phases.
+            e.g.
+            for one phase: "s0*G1",
+            for two phases: "s0*(s1*G1+(1-s1)*G2)",
+            for three phases: "s0*(s1*G1+s2*G2+(1-(s1+s2))*G3)",
+            ...
 
         Notes
         -----
         Planned features:
-        - Support registerFunction for custom equations.
+            - Support registerFunction for custom equations.
         """
         contribution = FitContribution("pdfcontribution")
         contribution.setProfile(self.profile)
@@ -216,10 +225,10 @@ def init_recipe(
         Notes
         -----
         Planned features:
-        - support instructions to
-            - add variables
-            - constrain variables of the scatters
-            - change symmetry constraints
+            - support instructions to
+                - add variables
+                - constrain variables of the scatters
+                - change symmetry constraints
         """
         recipe = FitRecipe()
         recipe.addContribution(self.contribution)
@@ -302,20 +311,25 @@ def get_variable_names(self) -> list[str]:
         return list(self.recipe._parameters.keys())
 
     def save_results(
-        self, mode: Literal["dict", "str"] = "str", filename=None
+        self, mode: Literal["str", "dict"] = "str", filename=None
     ):
         """Save the fitting results. Must be called after
         refine_parameters.
 
         Parameters
         ----------
-        filename : str | None
+        mode : str
+            The format to save the results. Options are:
+                "str" - Save results as a formatted text string.
+                "dict" - Save results as a JSON-compatible dictionary.
+        filename : str
             The path to the output file. If None, results will not be saved to
-            a file. The default is None.
-        mode : {"dict", "str"}
-            The format to save the results.
-            "str" - Save results as a formatted text string.
-            "dict" - Save results as a JSON-compatible dictionary.
+            a file.
+
+        Returns
+        -------
+        str or dict
+            The fitting results in the specified format.
         """
         fit_results = FitResults(self.recipe)
         if mode == "str":
