From e21a7b407f3a3c79366ccbb0f74eda8c92e1e304 Mon Sep 17 00:00:00 2001 From: Kai Striega Date: Thu, 21 Mar 2024 14:18:35 +1100 Subject: [PATCH] DOC: build dev documentation This PR builds the development documentation with sphinx. It required moving the existing files from the root directory to the ``doc`` directory. --- doc/source/conf.py | 1 + .../source/dev}/building_with_poetry.md | 0 .../source/dev}/getting_the_code.md | 0 .../source/dev}/running_the_benchmarks.md | 0 .../doc_developer/building_with_poetry.rst | 64 ------------------- doc/source/doc_developer/getting_the_code.rst | 48 -------------- doc/source/index.rst | 5 +- pyproject.toml | 1 + 8 files changed, 5 insertions(+), 114 deletions(-) rename {doc_developer => doc/source/dev}/building_with_poetry.md (100%) rename {doc_developer => doc/source/dev}/getting_the_code.md (100%) rename {doc_developer => doc/source/dev}/running_the_benchmarks.md (100%) delete mode 100644 doc/source/doc_developer/building_with_poetry.rst delete mode 100644 doc/source/doc_developer/getting_the_code.rst diff --git a/doc/source/conf.py b/doc/source/conf.py index da27bcf..e0866a1 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -33,6 +33,7 @@ 'sphinx.ext.autodoc', 'numpydoc', 'sphinx.ext.mathjax', + 'myst_parser', ] # Add any paths that contain templates here, relative to this directory. diff --git a/doc_developer/building_with_poetry.md b/doc/source/dev/building_with_poetry.md similarity index 100% rename from doc_developer/building_with_poetry.md rename to doc/source/dev/building_with_poetry.md diff --git a/doc_developer/getting_the_code.md b/doc/source/dev/getting_the_code.md similarity index 100% rename from doc_developer/getting_the_code.md rename to doc/source/dev/getting_the_code.md diff --git a/doc_developer/running_the_benchmarks.md b/doc/source/dev/running_the_benchmarks.md similarity index 100% rename from doc_developer/running_the_benchmarks.md rename to doc/source/dev/running_the_benchmarks.md diff --git a/doc/source/doc_developer/building_with_poetry.rst b/doc/source/doc_developer/building_with_poetry.rst deleted file mode 100644 index 36cb88c..0000000 --- a/doc/source/doc_developer/building_with_poetry.rst +++ /dev/null @@ -1,64 +0,0 @@ -==================== -Building with poetry -==================== - -Installing poetry -================= - -numpy-financial uses `poetry `__ to manage -dependencies, build wheels and sdists, and publish to PyPI this page documents -how to work with poetry. - -To install poetry follow their `official guide `__. -It is recommended to use the official installer for local development. - -To check your installation try to check the version of poetry:: - - poetry -V - - -Setting up a virtual environment using poetry -============================================= - -Once poetry is installed it is time to set up the virtual environment. To do -this, run:: - - poetry install - - -``poetry install`` looks for dependencies in the ``pyproject.toml`` file, -resolves them to the most recent version and installs the dependencies -in a virtual environment. It is now possible to launch an interactive REPL -by running the following command:: - - poetry run python - -Running the test suite -====================== - -``numpy-financial``` has an extensive test suite, which can be run with the -following command:: - - poetry run pytest - -Building distributions -====================== - -It is possible to manually build distributions for ``numpy-financial`` using -poetry. This is possible via the ``build`` command:: - - poetry build - -The ``build`` command creates a ``dist`` directory containing a wheel and sdist -file. - -Publishing to PyPI -================== - -poetry provides support to publish packages to PyPI. This is possible using -the ``publish`` command:: - - poetry publish --build --username --password - -Note that this builds the package before publishing it. You will need to -provide the correct username and password for PyPI. diff --git a/doc/source/doc_developer/getting_the_code.rst b/doc/source/doc_developer/getting_the_code.rst deleted file mode 100644 index 99a771e..0000000 --- a/doc/source/doc_developer/getting_the_code.rst +++ /dev/null @@ -1,48 +0,0 @@ -================ -Getting the code -================ - -This document explains how to get the source code for NumPy-Financial using Git. - -Code Location -============= - -NumPy-Financial is hosted on GitHub. The repository URL is -https://github.com/numpy/numpy-financial. - -Creating a fork -=============== - -To create a fork click the green "fork" button at the top right of the page. -This creates a new repository on your GitHub profile. This will have the URL: -``https://github.com//numpy-financial``. - -Cloning the repository -====================== - -Now that you have forked the repository you will need to clone it. This copies -the repository from GitHub to the local machine. To clone a repository enter the -following commands in the terminal:: - - git clone https://github.com//numpy-financial.git - -Hooray! You now have a working copy of NumPy-Financial. - - -Updating the code with other's changes -====================================== - -From time to time you may want to pull down the latest code. Do this with:: - - git fetch - -The ``git fetch`` command downloads commits, files and refs from a remote repo -into your local repo. - -Then run:: - - git merge --ff-only - -The ``git merge`` command is Git's way of putting independent branches back -together. The ``--ff-only`` flag tells git to use ``fast-forward`` merges. This -is preferable as fast-forward merge avoids creating merge commits. \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index f8fb19e..93d67c2 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -65,8 +65,9 @@ Development .. toctree:: :maxdepth: 1 - doc_developer/getting_the_code - doc_developer/building_with_poetry + dev/getting_the_code.md + dev/building_with_poetry.md + dev/running_the_benchmarks.md .. include:: release-notes.rst diff --git a/pyproject.toml b/pyproject.toml index 0dd3e96..a2527ce 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -48,6 +48,7 @@ pytest = "^8.0" sphinx = "^7.0" numpydoc = "^1.5" pydata-sphinx-theme = "^0.14.3" +myst-parser = "^2.0.0"