Merge pull request #14 from SMI-Lab-Inha/docs-links-and-changelog

Fix doc links, changelog rendering, and beginner install

Author: SMI-Lab-Inha

README.md

@@ -18,17 +18,21 @@ It targets compatibility with selected legacy *IECWind*-style workflows. It has
 
 ## Installation
 
-`pyIECWind` is not yet on PyPI. Install from source:
+`pyIECWind` is not yet on PyPI. The simplest, most reliable setup is a conda
+environment (install [Miniconda](https://www.anaconda.com/docs/getting-started/miniconda/install)
+first if you don't already use Python):
 
 ```bash
 git clone https://github.com/SMI-Lab-Inha/pyIECWind.git
 cd pyIECWind
-python -m pip install -e .
+conda env create -f environment.yml
+conda activate pyiecwind
 ```
 
-Conda and development installs are described in
-[docs/installation.rst](docs/installation.rst). A PyPI release and a conda-forge
-package are planned.
+The [Installation guide](https://pyiecwind.readthedocs.io/en/latest/installation.html)
+has a step-by-step walkthrough (recommended if you're new to Python), plus
+pip-only and development installs. A PyPI release and a conda-forge package are
+planned.
 
 ## Usage
 
@@ -75,12 +79,13 @@ closed (raises on the first invalid condition) unless `strict=False`.
 - Speed modifiers are valid only on the rated (`R`) reference.
 - This package generates inflow files; it does not run OpenFAST.
 
-Full detail: [docs/limitations.rst](docs/limitations.rst).
+Full detail: [Scope and limitations](https://pyiecwind.readthedocs.io/en/latest/limitations.html).
 
 ## Validation
 
 Output is protected by three layers of differing strength, documented with a
-per-scenario reproducibility matrix in [docs/validation.rst](docs/validation.rst):
+per-scenario reproducibility matrix in the
+[Validation docs](https://pyiecwind.readthedocs.io/en/latest/validation.html):
 
 1. **Golden regression corpus** - committed reference `.wnd` files regenerated and
    compared on every run. These are generated by this package, so they detect
@@ -101,9 +106,11 @@ layer is future work.
 
 Hosted at [pyiecwind.readthedocs.io](https://pyiecwind.readthedocs.io/en/latest/)
 (source in [`docs/`](docs/), built with Sphinx). Highlights:
-[Theory](docs/theory.rst) (IEC equations), [API reference](docs/api.rst),
-[API contract](docs/api_contract.rst), [Input files](docs/data_sources.rst),
-[Units](docs/units.rst).
+[Theory](https://pyiecwind.readthedocs.io/en/latest/theory.html) (IEC equations),
+[API reference](https://pyiecwind.readthedocs.io/en/latest/api.html),
+[API contract](https://pyiecwind.readthedocs.io/en/latest/api_contract.html),
+[Input files](https://pyiecwind.readthedocs.io/en/latest/data_sources.html),
+[Units](https://pyiecwind.readthedocs.io/en/latest/units.html).
 
 ## Development
 
@@ -114,7 +121,8 @@ mypy
 pytest --cov=pyiecwind
 ```
 
-Quality gates and contribution guidelines: [docs/contributing.rst](docs/contributing.rst).
+Quality gates and contribution guidelines:
+[Contributing](https://pyiecwind.readthedocs.io/en/latest/contributing.html).
 
 ## Citation
 
@@ -130,8 +138,8 @@ file under *Cite this repository*.
 - OpenFAST *InflowWind* module documentation, National Laboratory of the Rockies
   (formerly the National Renewable Energy Laboratory).
 
-See [docs/theory.rst](docs/theory.rst) for the equations and their mapping to the
-implementation.
+See the [Theory](https://pyiecwind.readthedocs.io/en/latest/theory.html) page for
+the equations and their mapping to the implementation.
 
 ## License
 

docs/changelog.rst

@@ -1,9 +1,5 @@
-Changelog
-=========
+.. This page renders the canonical CHANGELOG.md (single source) via MyST, so it
+   never drifts. The page title comes from the Markdown H1.
 
-The changelog is maintained as a single source in ``CHANGELOG.md`` at the
-repository root and is included verbatim below, so this page never drifts out of
-sync with it.
-
-.. literalinclude:: ../CHANGELOG.md
-   :language: markdown
+.. include:: ../CHANGELOG.md
+   :parser: myst_parser.sphinx_

docs/conf.py

@@ -26,6 +26,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "sphinx.ext.mathjax",
+    "myst_parser",  # only to parse the included Markdown CHANGELOG (see changelog.rst)
 ]
 
 source_suffix = {".rst": "restructuredtext"}

docs/installation.rst

@@ -6,36 +6,68 @@ Installation
 .. note::
 
    ``pyIECWind`` is not yet published on PyPI, so ``pip install pyiecwind`` is not
-   available. Install from source or conda as shown below. A PyPI release and a
-   ``conda-forge`` package are planned (see :doc:`deployment`).
+   available. Install from source, ideally inside a conda environment as shown
+   below. A PyPI release and a ``conda-forge`` package are planned (see
+   :doc:`deployment`).
 
-From source
------------
+Recommended: Miniconda (step by step)
+-------------------------------------
+
+If you are coming from an engineering background and do not already have a Python
+workflow, this is the most reliable way to get started. It installs an isolated
+environment so ``pyIECWind`` cannot interfere with any other Python on your
+machine.
+
+**1. Install Miniconda.** Download and run the installer for your operating system
+from https://www.anaconda.com/docs/getting-started/miniconda/install. Miniconda is
+a small distribution that provides ``conda`` (an environment and package manager)
+and Python. On Windows, accept the defaults and then open the **Anaconda Prompt**;
+on macOS/Linux, open a terminal.
+
+**2. Get the code.** Clone the repository (or download the ZIP from GitHub and
+extract it), then change into the folder:
+
+.. code-block:: console
+
+   git clone https://github.com/SMI-Lab-Inha/pyIECWind.git
+   cd pyIECWind
+
+**3. Create the environment.** This reads ``environment.yml`` and builds an
+isolated environment named ``pyiecwind`` with the correct Python, NumPy, and
+``pyIECWind`` itself:
 
 .. code-block:: console
 
-   $ git clone https://github.com/SMI-Lab-Inha/pyIECWind.git
-   $ cd pyIECWind
-   $ python -m pip install -e .
+   conda env create -f environment.yml
+
+**4. Activate it.** Do this in every new terminal session before using the tool:
+
+.. code-block:: console
 
-Conda
------
+   conda activate pyiecwind
 
-Create the provided environment:
+**5. Check it works:**
 
 .. code-block:: console
 
-   $ conda env create -f environment.yml
-   $ conda run -n pyiecwind pyiecwind --help
+   pyiecwind --help
+
+You are ready -- continue with the :doc:`quickstart`.
+
+Alternative installs
+--------------------
 
-or install into an existing environment:
+If you already manage your own Python environments:
 
 .. code-block:: console
 
-   $ conda create -n pyiecwind python=3.11 numpy pip -y
-   $ conda run -n pyiecwind python -m pip install -e .
+   # into an existing conda environment
+   conda create -n pyiecwind python=3.11 numpy pip -y
+   conda activate pyiecwind
+   python -m pip install -e .
 
-A ``conda-forge`` package is planned; see :doc:`deployment`.
+   # or a plain pip install from a source checkout
+   python -m pip install -e .
 
 Optional dependency groups
 --------------------------
@@ -44,23 +76,24 @@ Two extras are available for contributors:
 
 ``dev``
     Test and quality tooling: ``pytest``, ``pytest-cov``, ``hypothesis``,
-    ``ruff``, ``mypy``, ``build``, and ``twine``.
+    ``ruff``, ``mypy``, ``build``, ``twine``, and ``pip-audit``.
 
 ``docs``
-    Documentation tooling: ``sphinx`` and the ``furo`` theme.
+    Documentation tooling: ``sphinx``, the ``sphinx-rtd-theme`` theme, and
+    ``myst-parser``.
 
 .. code-block:: console
 
-   $ python -m pip install -e ".[dev]"
-   $ python -m pip install -e ".[docs]"
+   python -m pip install -e ".[dev]"
+   python -m pip install -e ".[docs]"
 
 Verifying the installation
 --------------------------
 
 .. code-block:: console
 
-   $ pyiecwind --help
-   $ python -c "import pyiecwind; print(pyiecwind.__version__)"
+   pyiecwind --help
+   python -c "import pyiecwind; print(pyiecwind.__version__)"
 
-The version is single-sourced from the installed package metadata, so the
-import above and ``pip show pyiecwind`` always agree.
+The version is single-sourced from the installed package metadata, so the import
+above and ``pip show pyiecwind`` always agree.

pyproject.toml

@@ -45,6 +45,7 @@ dev = [
 docs = [
   "sphinx>=7.0",
   "sphinx-rtd-theme>=2.0",
+  "myst-parser>=2.0",
 ]
 
 [project.scripts]