Skip to content

docs: initialize the documentation #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sbillinge merged 4 commits into from
Feb 5, 2026
Merged

docs: initialize the documentation #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d63fe78
docs: initialize the documentation
ycexiao Feb 4, 2026
3600c60
chore: add news file
ycexiao Feb 4, 2026
f4420ef
docs: be explicit about the default behaviorsin the functions' docsti…
ycexiao Feb 4, 2026
dd7446d
chore: modify the function docstring about the default behaviors
ycexiao Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 0 additions & 31 deletions docs/source/api/pdfbl.sequential.example_package.rst
View file
Open in desktop

This file was deleted.

22 changes: 13 additions & 9 deletions docs/source/api/pdfbl.sequential.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
71 changes: 2 additions & 69 deletions docs/source/getting-started.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
28 changes: 0 additions & 28 deletions docs/source/snippets/example-table.rst
View file
Open in desktop

This file was deleted.

23 changes: 23 additions & 0 deletions news/init-doc.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
82 changes: 48 additions & 34 deletions src/pdfbl/sequential/pdfadapter.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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()
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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.
Copy link
Copy Markdown
Contributor Author

@ycexiao ycexiao Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Examples added.

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)
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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":
Expand Down
Loading