build documentation

docs/pages/0.1.0/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 82d774369f9c51c579663b789dc92786
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/pages/0.1.0/.buildinfo.bak

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 6150c9aff1ecb932da090e615cbab94d
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/pages/0.1.0/_sources/api_reference/example.rst.txt

@@ -0,0 +1,5 @@
+raking.example
+=============
+
+.. automodule:: raking.example
+   :members:

docs/pages/0.1.0/_sources/api_reference/index.rst.txt

@@ -0,0 +1,13 @@
+API reference
+=============
+
+.. toctree::
+   :hidden:
+   :glob:
+
+   *
+
+.. note::
+   Briefly describe the organization of the API reference if any.
+
+In PyPkg, we only provide a dummy function :py:func:`.example.add` to show the bone structure of a Python pacakge.

docs/pages/0.1.0/_sources/developer_guide/index.rst.txt

@@ -0,0 +1,11 @@
+Developer guide
+===============
+
+.. admonition:: Work in progress...
+    :class: attention
+
+    Current topics
+
+    * briefly describe how to contribute
+    * contributing to the documentation
+    * contributing to the code base

docs/pages/0.1.0/_sources/getting_started/index.rst.txt

@@ -0,0 +1,25 @@
+Getting started
+===============
+
+.. toctree::
+   :hidden:
+
+   installation
+   quickstart
+
+.. note::
+
+    This page can be used to introduce some basic concepts to beginners.
+    It should be welcoming and not technical.
+    You can also use it address some of the pre-requisites for the package.
+
+
+Welcome to PyPkg!
+-----------------
+
+PyPkg package is a template package.
+It tries to show the basic bone structure of a package with minimal functionality.
+It is meant to be used as a starting point for new packages.
+
+For installing the package please check :ref:`Installing PyPkg`.
+For a simple example please check :ref:`Quickstart`.

docs/pages/0.1.0/_sources/getting_started/installation.rst.txt

@@ -0,0 +1,31 @@
+================
+Installing raking
+================
+
+Python version
+--------------
+
+The package :code:`raking` is written in Python and requires Python 3.11 or later.
+
+This is a development version of the package and it is not yet available on PyPI. To install it locally, please use:
+
+.. code::
+
+    git clone "https://github.com/ihmeuw-msca/raking.git"
+    cd raking
+    python3 -m venv .venv
+    source .venv/bin/activate
+    python3 -m pip install --upgrade pip
+    python3 -m pip install ipykernel
+    python3 -m pip install jupyterlab
+    python3 -m pip install notebook
+    pip install -e .
+    python3 -m ipykernel install --user --name env_raking --display-name "env_raking"
+
+Then launch Jupyter notebook using:
+
+.. code::
+
+    jupyter notebook
+
+Open the notebook getting_started.ipynb and change the kernel to "env_raking" on the top right of the page. You can then run the examples.

docs/pages/0.1.0/_sources/getting_started/quickstart.rst.txt

@@ -0,0 +1,33 @@
+==========
+Quickstart
+==========
+
+Example 1
+---------
+
+This is how to use the raking packkage when we do not have draws and we do not want the covariance matrix of the raked values.
+
+.. code-block:: python
+
+    from raking.run_raking import run_raking
+
+    # 1D example
+    df_obs = pd.read_csv('YOUR_PATH/tests/examples/example_1D/observations.csv')
+    df_margin = pd.read_csv('YOUR_PATH/tests/examples/example_1D/margin.csv')
+
+    (df_raked, dummy1, dummy2, dummy3) = run_raking(1, df_obs, [df_margin], ['var1'], cov_mat=False)
+
+    # 2D example
+    df_obs = pd.read_csv('YOUR_PATH/tests/examples/example_2D/observations.csv')
+    df_margins_1 = pd.read_csv('YOUR_PATH/tests/examples/example_2D/margins_1.csv')
+    df_margins_2 = pd.read_csv('YOUR_PATH/tests/examples/example_2D/margins_2.csv')
+
+    (df_raked, dummy1, dummy2, dummy3) = run_raking(2, df_obs, [df_margins_1, df_margins_2], ['var1', 'var2'], cov_mat=False)
+
+    # 3D example
+    df_obs = pd.read_csv('YOUR_PATH/tests/examples/example_3D/observations.csv')
+    df_margins_1 = pd.read_csv('YOUR_PATH/tests/examples/example_3D/margins_1.csv')
+    df_margins_2 = pd.read_csv('YOUR_PATH/tests/examples/example_3D/margins_2.csv')
+    df_margins_3 = pd.read_csv('YOUR_PATH/tests/examples/example_3D/margins_3.csv')
+
+    (df_raked, dummy1, dummy2, dummy3) = run_raking(3, df_obs, [df_margins_1, df_margins_2, df_margins-3], ['var1', 'var2', 'var3'], cov_mat=False)

docs/pages/0.1.0/_sources/index.rst.txt

@@ -0,0 +1,32 @@
+PyPkg documentation
+===================
+
+.. toctree::
+   :hidden:
+
+   getting_started/index
+   user_guide/index
+   api_reference/index
+   developer_guide/index
+
+Raking is a well known method in survey sampling to adjust the cases in a contingency table to match the known marginal totals. This package has been developed to rake 1, 2 and 3D contingency tables.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+
+   * - :ref:`Getting started`
+     - :ref:`User guide`
+
+   * - How to install the package.
+     - The user guide provides in-depth information on key concepts of raking and what you can do with the package.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+
+   * - :ref:`API reference`
+     - :ref:`Developer guide`
+
+   * - If you are looking for information on a specific module, function, class or method, this part of the documentation is for you.
+     - Want to improve the existing functionalities and documentation? The contributing guidelines will guide you through the process.

docs/pages/0.1.0/_sources/user_guide/cicd.rst.txt

@@ -0,0 +1,9 @@
+CI/CD
+=====
+
+.. admonition:: Working in progress...
+    :class: attention
+
+    * introduce some basic concept of continuous integration and deployment
+    * introduce github workflow
+    * introduce badges

docs/pages/0.1.0/_sources/user_guide/documentation.rst.txt

@@ -0,0 +1,8 @@
+Documentation
+=============
+
+.. admonition:: Working in progress...
+    :class: attention
+
+    * introduce sphinx
+    * describe the multi-version documentation building process

docs/pages/0.1.0/_sources/user_guide/index.rst.txt

@@ -0,0 +1,22 @@
+User guide
+==========
+
+.. toctree::
+   :hidden:
+   :numbered:
+
+   project_organization
+   style_guide
+   testing
+   documentation
+   cicd
+
+.. note::
+
+   Please provide some intructions of how to read the user guide here.
+   For example where should a user start and what order of reading should one follow.
+
+
+This user guide introduces and explains some key concepts when building a Python package.
+If you are a new user starting out your Python package journey, we recommend you to start with the
+:ref:`Project organization` and read each section in order.

docs/pages/0.1.0/_sources/user_guide/project_organization.rst.txt

@@ -0,0 +1,42 @@
+Project organization
+====================
+
+.. admonition:: Working in progress...
+    :class: Attention
+
+    Explain what different files and folders in the repo mean...
+
+Here we describe what each file and folder in the project means and provide references and examples.
+
+* :code:`.github/workflows`: GitHub Actions workflows for continuous integration and deployment.
+    * For more please check :ref:`CI/CD`.
+* :code:`.vscode`: VSCode configurations.
+    * We use `Visual Studio Code <https://code.visualstudio.com>`_ as our main IDE.
+    * `Getting Started with Python in VS Code <https://code.visualstudio.com/docs/python/python-tutorial>`_.
+* :code:`.gitignore`: Files and folders that are ignored by Git.
+    * For formal documentation please check `here <https://git-scm.com/docs/gitignore>`_.
+    * For more please check `the list of common gitignore <https://github.com/github/gitignore>`_.
+    * We use the `gitignore extension <https://marketplace.visualstudio.com/items?itemName=codezombiech.gitignore>`_ in VSCode to conveniently genterate gitignore file.
+* :code:`src`: Source code of the project.
+    * For a minimum example of the source folder, please check `A simple project <https://packaging.python.org/en/latest/tutorials/packaging-projects/#a-simple-project>`_.
+* :code:`docs`: Documentation of the project.
+    * We use `Sphinx <https://www.sphinx-doc.org/en/master/>`_ to build documentation.
+    * For more please check :ref:`Documentation`.
+* :code:`tests`: Tests of the project.
+    * We use `Pytest <https://docs.pytest.org/en/stable/>`_ as the testing framework.
+    * For more please check :ref:`Testing`.
+* :code:`pyproject.toml`: Metadata of the project. This is enssential for Python packaging.
+    * For more information please check `this guide <https://packaging.python.org/en/latest/guides/writing-pyproject-toml/>`_.
+* :code:`ruff.toml`: Configuration for `Ruff <https://docs.astral.sh/ruff/>`_ linter and formatter.
+    * For more please check :ref:`Style guide`.
+    * We use `Ruff extension <https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff>`_ in VSCode to lint and format the code.
+* :code:`LICENSE`: License of the project. Here are some references
+    * `Licensing a repository <https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository>`_.
+    * `Adding a license to a repository on GitHub <https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository>`_.
+    * Adding a license on VSCode with extention `Choose a License extension <https://marketplace.visualstudio.com/items?itemName=ultram4rine.vscode-choosealicense>`_.
+* :code:`README.md`: Main page of the project including
+    * Brief description of the project.
+    * Installation instructions.
+    * A quick example.
+* :code:`CODE_OF_CONDUCT.md`: Code of conduct of the project.
+    * `Adding a code of conduct to your project <https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project>`_.

docs/pages/0.1.0/_sources/user_guide/style_guide.rst.txt

@@ -0,0 +1,13 @@
+Style guide
+===========
+
+.. admonition:: Working in progress...
+    :class: Attention
+
+    Current topics
+
+    * PEP8
+    * naming
+    * linter/formatter
+    * docstrings
+    * type hints

docs/pages/0.1.0/_sources/user_guide/testing.rst.txt

@@ -0,0 +1,8 @@
+Testing
+=======
+
+.. admonition:: Working in progress...
+    :class: attention
+
+    * introduce Pytest
+    * introduce test covarage