MAINT: docs maintenance (WIP) (#740)

* fix theme for sphinx-rtd-theme * MAINT: work on docs and migrate info from org site * updates to docs * transfer links to rst * add sphinx-rtd-theme * fix links * fix issues from local builds * add install instruction for conda-forge * change order for setup * add note about different anaconda channels * update pages proof-read * Update docs/source/contributing.rst Co-authored-by: Daisuke Oyama <[email protected]> * Update docs/source/contributing.rst Co-authored-by: Daisuke Oyama <[email protected]> * update index.rst for rtd --------- Co-authored-by: Daisuke Oyama <[email protected]>
QuantEcon · Nov 27, 2024 · f214fdf · f214fdf
1 parent 494603d
commit f214fdf
Show file tree

Hide file tree

Showing 7 changed files with 134 additions and 252 deletions.
diff --git a/docs/make.bat b/docs/make.bat
diff --git 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
@@ -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
@@ -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
@@ -0,0 +1,49 @@
+Contribute to QuantEcon.py
+==========================
+
+If you would like to contribute to `QuantEcon.py <https://github.com/QuantEcon/QuantEcon.py>`_, 
+a good place to start is the `project issue tracker <http://github.com/QuantEcon/QuantEcon.py/issues>`_. 
+
+Set up a Conda development environment
+--------------------------------------
+
+One of the advantages of the `Anaconda Python environment <https://www.anaconda.com/download>`_ 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 <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_
+
+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 <https://numpydoc.readthedocs.io/en/latest/format.html>`_. 
+
+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 <https://quantecon.org/team>`_ on the 
+`Discourse forum <http://discourse.quantecon.org/>`_ if you have any further questions.
diff --git 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
 ==================