diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 61e864bbf..000000000 --- a/docs/make.bat +++ /dev/null @@ -1,242 +0,0 @@ -@ECHO OFF - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set BUILDDIR=build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% source -set I18NSPHINXOPTS=%SPHINXOPTS% source -if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% -) - -if "%1" == "" goto help - -if "%1" == "help" ( - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. xml to make Docutils-native XML files - echo. pseudoxml to make pseudoxml-XML files for display purposes - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* - goto end -) - - -%SPHINXBUILD% 2> nul -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\QuantEcon.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\QuantEcon.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdf" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf - cd %BUILDDIR%/.. - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdfja" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf-ja - cd %BUILDDIR%/.. - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -if "%1" == "xml" ( - %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The XML files are in %BUILDDIR%/xml. - goto end -) - -if "%1" == "pseudoxml" ( - %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. - goto end -) - -:end diff --git a/docs/qe_apidoc.py b/docs/qe_apidoc.py index b520f2928..d2208ee83 100644 --- a/docs/qe_apidoc.py +++ b/docs/qe_apidoc.py @@ -140,13 +140,15 @@ .. toctree:: :maxdepth: 2 + setup game_theory markov optimize random tools util - + contributing + Indices and tables ================== diff --git a/docs/rtd-requirements.txt b/docs/rtd-requirements.txt index 2cbad8323..ac08ff209 100644 --- a/docs/rtd-requirements.txt +++ b/docs/rtd-requirements.txt @@ -7,3 +7,4 @@ sympy scipy>=1.5 requests matplotlib +sphinx_rtd_theme diff --git a/docs/source/conf.py b/docs/source/conf.py index ca37505d0..5e6076b71 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -70,6 +70,7 @@ def install(package): # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx_rtd_theme', 'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.mathjax', @@ -153,13 +154,7 @@ def install(package): # -- Options for HTML output ---------------------------------------------- -on_rtd = os.environ.get('READTHEDOCS', None) == 'True' -if on_rtd: - html_theme = 'default' -else: # Local build. Need to import rtd theme - import sphinx_rtd_theme - html_theme = "sphinx_rtd_theme" - html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +html_theme = "sphinx_rtd_theme" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -188,7 +183,7 @@ def install(package): # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [''] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst new file mode 100644 index 000000000..9d2418236 --- /dev/null +++ b/docs/source/contributing.rst @@ -0,0 +1,49 @@ +Contribute to QuantEcon.py +========================== + +If you would like to contribute to `QuantEcon.py `_, +a good place to start is the `project issue tracker `_. + +Set up a Conda development environment +-------------------------------------- + +One of the advantages of the `Anaconda Python environment `_ is that it is +cheap to set up (and discard) Python environments for development versions of packages and populate them with your +favorite scientific tools. + +For example, if you're working on QuantEcon.py you might find it useful to set up an +environment (containing NumPy, SciPy, etc.) that uses your development version rather than the default ones. + +This facilitates contributing to QuantEcon.py without worrying about corrupting the Python environment on which your other work depends. + +You can learn more about `managing environments here `_ + +Write tests +----------- + +All functions and methods contributed to QuantEcon.py should be paired with tests to verify that they are functioning correctly. + +Write documentation +------------------- + +We try to maintain a simple and consistent format for inline documentation, known in the Python world as docstrings. + +The format we use is known as `numpydoc `_. + +It was developed by the numpy and scipy teams and is used in many popular packages. + +Adhering to this standard helps us + +* Provide a sense of consistency throughout the library +* Give users instant access to necessary information at the interpreter prompt (either via the built-in Python function help(object_name) or the Jupyter object_name?) +* Easily generate a reference manual using sphinx's autodoc and apidoc + +It is always useful to build the docs locally before setting up a pull request, and lets you check how your docstrings render in html prior to submitting a pull request. + +However once you open a PR a preview of the docs is provided as one of the GitHub Actions. + +Further questions +----------------- + +We encourage you to reach out to the `QuantEcon team `_ on the +`Discourse forum `_ if you have any further questions. diff --git a/docs/source/index.rst b/docs/source/index.rst index 6dcf25317..c85e21af4 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -11,13 +11,15 @@ mainly used by developers internal to the package. .. toctree:: :maxdepth: 2 + setup game_theory markov optimize random tools util - + contributing + Indices and tables ================== diff --git a/docs/source/setup.rst b/docs/source/setup.rst new file mode 100644 index 000000000..316f2b066 --- /dev/null +++ b/docs/source/setup.rst @@ -0,0 +1,75 @@ +Installation +============ + +Before installing `quantecon` we recommend you install the `Anaconda `_ Python distribution, +which includes a full suite of scientific python tools. + +Next you can install quantecon by opening a terminal prompt and typing + +.. code:: bash + + pip install quantecon + +and using `conda-forge` by typing + +.. code:: bash + + conda install -c conda-forge quantecon + +.. note:: + There are `quantecon` packages available in both the main `anaconda` channel + and the `conda-forge` channel. The official channel often lags behind the most + recent release that is available on `conda-forge` + + You can see the latest `versions here `_ + +Usage +----- + +Once `quantecon` has been installed you should be able to import it as follows: + +.. code:: python + + import quantecon as qe + +You can check the version by running + +.. code:: python + + print(qe.__version__) + +If your version is below what's available on `PyPI `_ then it is time to upgrade. + +This can be done by running + +.. code:: bash + + pip install --upgrade quantecon + +Downloading the `quantecon` Repository +-------------------------------------- + +An alternative is to download the sourcecode of the `quantecon` package and install it manually from +`the github repository `_. + +For example, if you have git installed type + +.. code:: bash + + git clone https://github.com/QuantEcon/QuantEcon.py + +Once you have downloaded the source files then the package can be installed by running + +.. code:: bash + + cd QuantEcon.py + pip install . + +(To learn the basics about setting up Git see `this link `_). + +Examples and Sample Code +------------------------ + +Many examples of QuantEcon.py in action can be found at `Quantitative Economics `_. + +QuantEcon.py is part of the QuantEcon organization (A NumFOCUS fiscally sponsored project). \ No newline at end of file