Merge pull request mmistakes#41 from ArWeHei/master

Documentation additions

.all-contributorsrc

@@ -0,0 +1,55 @@
+{
+    "projectName": "edflow",
+    "projectOwner": "PEsser",
+    "repoType": "github",
+    "repoHost": "https://github.com",
+    "files": ["README.md"],
+    "imageSize": 100,
+    "commit": false,
+    "commitConvention": "none",
+    "contributors": [
+        {
+            "login": "pesser",
+            "name": "Patrick Esser",
+            "avatar_url": "https://avatars3.githubusercontent.com/u/2175508?v=4",
+            "profile": "https://github.com/pesser",
+            "contributions": ["code"],
+        },
+        {
+            "login": "jhaux",
+            "name": "Johannes Haux",
+            "avatar_url": "https://avatars0.githubusercontent.com/u/9572598?v=4",
+            "profile": "https://github.com/jhaux",
+            "contributions": ["code"],
+        },
+        {
+            "login": "ArWeHei",
+            "name": "arwehei",
+            "avatar_url": "https://avatars2.githubusercontent.com/u/46443020?v=4",
+            "profile": "https://github.com/ArWeHei",
+            "contributions": ["doc"],
+        },
+        {
+            "login": "theRealSuperMario",
+            "name": "therealsupermario",
+            "avatar_url": "https://avatars0.githubusercontent.com/u/6517465?v=4",
+            "profile": "https://github.com/theRealSuperMario",
+            "contributions": ["example"],
+        },
+        {
+            "login": "mritv",
+            "name": "Ritvik Marwaha",
+            "avatar_url": "https://avatars1.githubusercontent.com/u/39053439?v=4",
+            "profile": "https://github.com/mritv",
+            "contributions": ["example"],
+        },
+        {
+            "login": "conrad784",
+            "name": "Conrad Sachweh",
+            "avatar_url": "https://avatars0.githubusercontent.com/u/6422533?v=4",
+            "profile": "https://conrad-sachweh.de",
+            "contributions": ["test"],
+        },
+    ],
+    "contributorsPerLine": 7,
+}

README.md

@@ -40,7 +40,7 @@ where `<env>` is one of the `yaml` files described above.
 
 ## Workflow
 
-For more information, look into our [starter guide](link).
+For more information, look into our [documentation](https://edflow.readthedocs.io/en/latest/).
 
 
 ## Example
@@ -104,3 +104,16 @@ Mimo Tilbich [![GitHub-Contributions][GitHub-Contributions]](https://github.com/
 [GitHub-Updated]: https://img.shields.io/github/last-commit/pesser/edflow/master.svg?logo=github&logoColor=white&label=pushed
 
 [LICENSE]: https://img.shields.io/github/license/pesser/edflow.svg
+
+## Contributors
+
+Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore -->
+<table><tr><td align="center"><a href="https://github.com/pesser"><img src="https://avatars3.githubusercontent.com/u/2175508?v=4" width="100px;" alt="Patrick Esser"/><br /><sub><b>Patrick Esser</b></sub></a><br /><a href="https://github.com/PEsser/edflow/commits?author=pesser" title="Code">💻</a></td><td align="center"><a href="https://github.com/jhaux"><img src="https://avatars0.githubusercontent.com/u/9572598?v=4" width="100px;" alt="Johannes Haux"/><br /><sub><b>Johannes Haux</b></sub></a><br /><a href="https://github.com/PEsser/edflow/commits?author=jhaux" title="Code">💻</a></td><td align="center"><a href="https://github.com/ArWeHei"><img src="https://avatars2.githubusercontent.com/u/46443020?v=4" width="100px;" alt="arwehei"/><br /><sub><b>arwehei</b></sub></a><br /><a href="https://github.com/PEsser/edflow/commits?author=ArWeHei" title="Documentation">📖</a></td><td align="center"><a href="https://github.com/theRealSuperMario"><img src="https://avatars0.githubusercontent.com/u/6517465?v=4" width="100px;" alt="therealsupermario"/><br /><sub><b>therealsupermario</b></sub></a><br /><a href="#example-theRealSuperMario" title="Examples">💡</a></td><td align="center"><a href="https://github.com/mritv"><img src="https://avatars1.githubusercontent.com/u/39053439?v=4" width="100px;" alt="Ritvik Marwaha"/><br /><sub><b>Ritvik Marwaha</b></sub></a><br /><a href="#example-mritv" title="Examples">💡</a></td><td align="center"><a href="https://conrad-sachweh.de"><img src="https://avatars0.githubusercontent.com/u/6422533?v=4" width="100px;" alt="Conrad Sachweh"/><br /><sub><b>Conrad Sachweh</b></sub></a><br /><a href="https://github.com/PEsser/edflow/commits?author=conrad784" title="Tests">⚠️</a></td></tr></table>
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
+   source/source_files/edflow

docs/conf.py

@@ -38,7 +38,6 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.viewcode",
     "sphinx.ext.githubpages",
-    "sphinx.ext.autosummary",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -80,12 +79,11 @@
     "natsort",
 ]
 
-autosummary_generate = True
-exclude_patterns = ["_build", "_templates"]
-
 autodoc_default_options = {
     "members": True,
     "member-order": "bysource",
     "special-members": "__init__",
     "undoc-members": True,
 }
+
+exclude_patterns = ["_build", "_templates"]

docs/index.rst

@@ -18,6 +18,7 @@ We created a user guide for you to use, have a look:
 Contents
 ========
 .. toctree::
+   :glob:
    :maxdepth: 2
 
    source/intro
@@ -28,7 +29,7 @@ Contents
    source/models
    source/iterator
    source/contributions
-   source/docu
+   source/source_files/edflow
 
 Indices and tables
 ==================

docs/source/contributions.rst

@@ -1,6 +1,5 @@
-
 Contributions
-=============
+*************
 
 If you have any new applications that require custom hooks or iterators feel
 free to contribute at any time.
@@ -9,7 +8,90 @@ free to contribute at any time.
 Examples of models are always welcome and we are happy if want to contribute in
 any way.
 
-We are working on github and celebrate every pull request ;).
+We are working on github and celebrate every pull request.
+
+black
+-----
+
+Before requesting a pull please run black_ for better code style or simply add
+black_ to your pre-commit hook:
+
+0. Install black_ with
+::
+   $ pip install black
+1. Paste the following into at the top <project-root>/.git/hooks/pre-commit.sample
+::
+   # run black on all staged files
+   staged=$(git diff --name-only --cached)
+   black $staged
+   # add them again after formatting
+   git add $staged
+2. Rename ``pre-commit.sample`` to ``pre-commit``
+3. Make it excutable using
+::
+   $ chmod +x pre-commit
+4. Done!
+
+Or run black by hand and use this command before every commit:
+::
+    black ./
+
+Continuous Integration
+======================
+
+We use travisCI_ for continuous integration.
+You do not need to worry about as long as your code passes all tests (this includes
+a formatting test with black).
+
+Documenation
+============
+
+   This is a short summary how the documentation works and how it can be built
+
+The documentation uses sphinx_ and is available under readthedocs.org_.
+It also uses all-contributors_ for honoring contributors.
+
+sphinx
+------
+
+To build the documentation locally, install `sphinx` and run:
+::
+    $ cd docs
+    $ make html
+
+The html files are available under the then existing direcotry ``docs/_build/html/``
+
+The docsting format which is preferred is `numpy`.
+
+We use `sphinx-apidoc` to track all files automatically:
+::
+    $ cd docs
+    $ sphinx-apidoc -o ./source/source_files ../edflow
+
+all-contirbutors
+----------------
+
+We use all-contributors locally and manage the contributors by hand.
+
+To do so, install `all-contributors` as described here (we advise you to install it inside the repo but unstage the added files).
+Then run the following command to add a contributor or contribution:
+::
+    all-contributors add <username> <contribution>
+
+If this does not work for you (sometimes with npm the case) use:
+::
+    ./node_modules/.bin/all-contributors add <username> <contribution>
+
+Known Issues
+------------
+
+We noticed that mocking `numpy` in ``config.py`` will not work due to some requirements when importing numpy in edflow.
+Thus we need to require numpy when building the documentation.
+
+Locally, this means that you need to have numpy installed in your environment.
+
+Concerning ``readthedocs.org``, this means that we require a ``readthedocs.yml`` in the source directory which points to ``extra_requirements`` in ``setup.py``, where numpy is a dependency.
+Other dependencies are `sphinx` and `sphinx_rtd_theme`.
 
 
 .. image:: https://img.shields.io/github/commit-activity/y/pesser/edflow.svg?logo=github&logoColor=white
@@ -41,3 +123,11 @@ We are working on github and celebrate every pull request ;).
    :target: https://img.shields.io/github/forks/pesser/edflow.svg?logo=github&logoColor=white
    :alt: GitHub-Forks
  <https://github.com/pesser/edflow/network>
+
+.. _black: https://github.com/ambv/black
+
+.. _readthedocs.org: https://edflow.readthedocs.io/en/latest/
+
+.. _all-contributors: https://allcontributors.org
+
+.. _travisCI: https://travis-ci.org/pesser/edflow/

docs/source/iterator.rst

@@ -1,6 +1,6 @@
 
-Documentation
-=============
+Iterators
+=========
 
 PyIterator
 ----------

docs/source/run_edflow.rst

@@ -1,6 +1,6 @@
 
 What Happens When I Run ``EDflow``
-==================================
+**********************************
 
 When you successfully build your model start ``EDflow`` with::
     edflow -t your_model/train.yaml

docs/source/source_files/edflow.applications.rst

@@ -0,0 +1,22 @@
+edflow.applications package
+===========================
+
+Submodules
+----------
+
+edflow.applications.tf\_perceptual\_loss module
+-----------------------------------------------
+
+.. automodule:: edflow.applications.tf_perceptual_loss
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: edflow.applications
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/source_files/edflow.data.rst

@@ -0,0 +1,30 @@
+edflow.data package
+===================
+
+Submodules
+----------
+
+edflow.data.dataset module
+--------------------------
+
+.. automodule:: edflow.data.dataset
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+edflow.data.util module
+-----------------------
+
+.. automodule:: edflow.data.util
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: edflow.data
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/source_files/edflow.hooks.checkpoint_hooks.rst

@@ -0,0 +1,38 @@
+edflow.hooks.checkpoint\_hooks package
+======================================
+
+Submodules
+----------
+
+edflow.hooks.checkpoint\_hooks.common module
+--------------------------------------------
+
+.. automodule:: edflow.hooks.checkpoint_hooks.common
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+edflow.hooks.checkpoint\_hooks.tf\_checkpoint\_hook module
+----------------------------------------------------------
+
+.. automodule:: edflow.hooks.checkpoint_hooks.tf_checkpoint_hook
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+edflow.hooks.checkpoint\_hooks.torch\_checkpoint\_hook module
+-------------------------------------------------------------
+
+.. automodule:: edflow.hooks.checkpoint_hooks.torch_checkpoint_hook
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: edflow.hooks.checkpoint_hooks
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/source_files/edflow.hooks.logging_hooks.rst

@@ -0,0 +1,22 @@
+edflow.hooks.logging\_hooks package
+===================================
+
+Submodules
+----------
+
+edflow.hooks.logging\_hooks.tf\_logging\_hook module
+----------------------------------------------------
+
+.. automodule:: edflow.hooks.logging_hooks.tf_logging_hook
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: edflow.hooks.logging_hooks
+    :members:
+    :undoc-members:
+    :show-inheritance: