removed target flag and wanted to try extlink plugin along with testing requirement and class info addition

Author: sagarlf

docs/python/classes.md

@@ -8,6 +8,17 @@ sidebar_label: Classes
 
 * Avoid inbuilt names.
 * Classes names should always be `PascalCase`. i.e. `MyClass` 
-* Even if you are building datatypes based on inbuilt class use PascalCase. i.e. `MyDict(dict):`
+* Use [abstract containers](https://docs.python.org/3/library/collections.abc.html#module-collections.abc) if need to override datatypes.
+    + If you must build datatypes based on inbuilt class use PascalCase. i.e. `MyDict(dict):`.
 * Describe the class responsibility in name.
 * Custom Exceptions should always be named ending with `Error` i.e. `MyCustomError`
+
+##### Example
+
+```
+class HelloWorld:
+    pass
+    
+class HelloWorldError(Exception):
+    pass
+```

docs/python/docstrings.md

@@ -139,6 +139,7 @@ The developers should add docstrings in the following locations
 - At the beginning of every class
 - After each function declaration
 - At the beginning of the `__init__.py` file for Module/Package documentation
+- In their tests to describe what they are testing.
 
 ### What to not miss
 
@@ -155,9 +156,9 @@ to check that your docstrings render correctly
 
 ### Checking Docstring coverage
 
-If you want to check docstring coverage in your project. Try interrogate (example below)
+- Use [pycodestyle](https://pycodestyle.pycqa.org/en/latest/) for linting your code against docstrings. When using `flake8`, [this](https://gitlab.com/pycqa/flake8-docstrings) plugin can be used.
+- [interrogate](https://interrogate.readthedocs.io/en/latest/) (example below) is **recommended** to use for docstring coverage in the code.
 
-- [interrogate](https://interrogate.readthedocs.io/en/latest/)
 
 ```
 
@@ -547,7 +548,3 @@ Thanks to the following
 - [Documenting in Python - DevGuide](https://devguide.python.org/documenting/)
 - [daouzli - stackoverflow](https://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format)
 - [interrogate](https://interrogate.readthedocs.io/en/latest/)
-
-
-
- 

docs/python/environment_and_dependency.md

@@ -10,14 +10,14 @@ sidebar_label: Environment Isolation and Dependency Management
 
 * System installed `python` should never be used for development. Isolate your development.
 * Any of the following can be used for python isolation:
-    - [pyenv](https://github.com/pyenv/pyenv){:target="_blank"}. **Recommended** as this supports local python install and multiple python versions.
-    - [virtualenv](https://virtualenv.pypa.io/en/latest/){:target="_blank"}. _Third Party_
-    - [venv](https://docs.python.org/3/tutorial/venv.html){:target="_blank"}. _Inbuilt_ `python -m venv`
+    - [pyenv](https://github.com/pyenv/pyenv). **Recommended** as this supports local python install and multiple python versions.
+    - [virtualenv](https://virtualenv.pypa.io/en/latest/). _Third Party_
+    - [venv](https://docs.python.org/3/tutorial/venv.html). _Inbuilt_ `python -m venv`
 * Use `pip` for installing packages if not using `poetry`.
 
 
 
 ##### Dependency Management:
 
-* [poetry](https://python-poetry.org/){:target="_blank"} is recommended as it handles dependency as well as build system.
+* [poetry](https://python-poetry.org/) is recommended as it handles dependency as well as build system.
 * You can use `setuptools` and `setup.py` as well for requirements handling through `requires`. They **must** be used for install-able modules.

docs/python/functions.md

@@ -12,3 +12,21 @@ sidebar_label: Functions
 * for bound methods in class `self` should be used for first argument.
 * for class methods in class `cls` should be used for first argument.
 * `decorators` should be named in function convention.
+
+
+```
+def get_db_connection(username, db_name):
+    return connection
+    
+#method
+
+def get_db_connection(self, username, db_name):
+    return connection
+    
+
+# classmethod
+@classmethod
+def multiple_param_initializer(cls, cls_param):
+    return cls(cls_param)
+    
+```

docs/python/general.md

@@ -6,6 +6,7 @@ sidebar_label: General Coding Guidelines
 
 #### These are the general guidelines to be followed:
 
+* See [tools](tools.md) that can be used in development environment setup to ease your coding process. 
 * Always use `python3` and try to stay above version `3.5`. **Latest stable** is recommended.
 * Indentation should always be **space** and width should always be **4**.
 * File size and functionality:
@@ -19,19 +20,21 @@ sidebar_label: General Coding Guidelines
     - `classmethod` for multiple way of class initialization
 * Imports:
     - Always `import` specific namespace.
-    - Try to use parent namespace for actions. i.e. `import os: os.path` rather that `from os import path`
+    - Try to use parent namespace for actions. i.e. `import sys: sys.path` rather that `from sys import path`
     - Never use `import *` i.e. `from MODULE import *`
     - use namespace whenever possible. Use `as SOMEOTHERNAMESPACE` for collision of namespace
 * Use `else: #nobreak` if you are using `else` with loops that has `break`.
-* use `mypy` and type annotation when possible for type safe code.
-* `Docker` can be used for deployment. Use `python` images for [docker](https://hub.docker.com/_/python){:target="_blank"}.
+* Use `pathlib` for path related use case rather than `os.path`
+* Use `mypy` and type annotation when possible for type safe code.
+* `Docker` can be used for deployment. Use `python` images for [docker](https://hub.docker.com/_/python).
 * Use `generators` and `yield` instead of data structures for high streams of data.
 * Use `itertools`, `functools` for utilities and `collection` for data structures.
 * Use `dataclasses` if available. Go for `attrs` library if `dataclass` is not present.
 * Use `is not` and `is` for `None`, `True` and `False` specific check only. If most cases truthy and falsy can be checked with if `VARNAME:`. 
 * Strings: 
     - Adhere to one quote practice. Double quote is recommended. Python doesnot differentiate between **'** or **"**.
-    - Should be interpolated with either [fstring](https://www.python.org/dev/peps/pep-0498/){:target="_blank"} or `.format` methods. Try to avoid `%`.
+    - Should be interpolated with either [fstring](https://www.python.org/dev/peps/pep-0498/) or `.format` methods. Try to avoid `%`.
+        + `format_map` should be used for key mapped formatting.
     - `+` can be used for direct string concatenation. Use `join` method for concatenation instead of `+=` when iterating.
 * Use `context` whenever supported especially for io related closing actions.
     - i.e. `with` statement when supported.
@@ -45,8 +48,8 @@ sidebar_label: General Coding Guidelines
     - Use `asyncio` for IO bound async flow. This is something new and constantly changing in `python`.
 * Recommended third party modules:
     - For Relational Database:
-        + Use `sqlalchemy` [core](https://docs.sqlalchemy.org/en/13/core/){:target="_blank"} for DB abstraction. This is particularly helpful when doing testing in `sqlite` and some other database for production. Also, for query consistency.
-        + Use `sqlalchemy` [ORM](https://docs.sqlalchemy.org/en/13/orm/){:target="_blank"} or framework supported ORM when using specific framework.
+        + Use `sqlalchemy` [core](https://docs.sqlalchemy.org/en/13/core/) for DB abstraction. This is particularly helpful when doing testing in `sqlite` and some other database for production. Also, for query consistency.
+        + Use `sqlalchemy` [ORM](https://docs.sqlalchemy.org/en/13/orm/) or framework supported ORM when using specific framework.
         + Use DBAPI drivers such as `pyodbc`, `sqlite`, `mysqlclient` etc only when you donot want `sqlalchemy` dependency or when you are very performance conscious. While the API will be mostly compatible for this as python has DBAPI specification. Parameters binding and some methods may be incompatible or unavailable. 
     - `requests` for http request stuff.
     - `attrs` for data oriented objects and class.

docs/python/project_structure.md

@@ -18,13 +18,19 @@ sidebar_label: Project Structure
         + :file_folder: service
         + :file_folder: config
     - :file_folder: tests
-        + test of projects
+        + :file_folder: test of projects
+        + :memo: conftest.py
     - :memo: LICENSE (**OPTIONAL**)
     - :memo: README (can be `md` or `rst`)
     - Other configurable from third parties (**OPTIONAL**) such as tox.ini
 
 
++ **There can be cases where MVC folder structure as well as framework related folder structure can be used.** 
+    - The framework recommended structure shoudl be followed in such case.
++ The OOP style cases of class as filename structue is not always necessary but can be used if needed.
+
+
 
 ##### Template Generation: 
-* Look into [cookiecutter](https://cookiecutter.readthedocs.io/en/1.7.2/){:target="_blank"} tool for template generation.
-    - [List of templates for cookiecutter](http://cookiecutter-templates.sebastianruml.name/){:target="_blank"}
+* Look into [cookiecutter](https://cookiecutter.readthedocs.io/en/1.7.2/) tool for template generation.
+    - [List of templates for cookiecutter](http://cookiecutter-templates.sebastianruml.name/)

docs/python/testing.md

@@ -0,0 +1,21 @@
+---
+id: testing
+title: Testing in `python`
+sidebar_label: Testing
+---
+
+### Test is integral part of sofware quality and should not be missed.
+
+
+
+* Always use `pytest` for testing codes.
+    + `unittest` provided by standard python can be used too if there is some blockage in using `pytest`.
+* `tox` and `nox` are vey good tools especially for CI and multiple version tests.
+* `hypothesis` and `mock` can be used for faking data and property testing.
+* Testing should be broken to `unit` as well as `functional`.
+* Use `coverage` to alert yourself of test coverage.
+* Only test the changes you made or functionality you added when testing a codebase of well known frameworks.
+* `selenium` as well as `webtest` can be used for web based API testing.
+* `jsonschema` and `genson` like tool can be used for JSON validity.
+* Always confirm the `schema` when testing Web API response data.
+* Passing tests for `merge` should be priority for all projects.

docs/python/tools.md

@@ -2,39 +2,44 @@
 id: tools
 title: Tools to use for easing development and maintaining consistency. There are links to readings as well.
 sidebar_label: Tools and Libraries
----
+--- 
+
+:::info 
+These tools can be used along with your development environment and IDE so that you can follow coding conventions better.
+:::
 
 #### Templates:
-* [cookiecutter](https://cookiecutter.readthedocs.io/en/1.7.2/){:target="_blank"}
+* [cookiecutter](https://cookiecutter.readthedocs.io/en/1.7.2/)
 
 #### Dependency Management:
-* [poetry](https://python-poetry.org/){:target="_blank"}
+* [poetry](https://python-poetry.org/)
 
 #### Linters:
-* [flake8](https://flake8.pycqa.org/en/latest/){:target="_blank"} with [plugins](https://github.com/DmytroLitvinov/awesome-flake8-extensions){:target="_blank"}
-    * Alternative: [pylint](https://www.pylint.org){:target="_blank"}
-* [bandit](https://bandit.readthedocs.io/en/latest/){:target="_blank"} to find common security issues. This can be used with `flake8` as a [plugin](https://pypi.org/project/flake8-bandit/){:target="_blan.k"}
+* [flake8](https://flake8.pycqa.org/en/latest/) with [plugins](https://github.com/DmytroLitvinov/awesome-flake8-extensions)
+    * Alternative: [pylint](https://www.pylint.org)
+* [bandit](https://bandit.readthedocs.io/en/latest/) to find common security issues. This can be used with `flake8` as a [plugin](https://pypi.org/project/flake8-bandit/)
 
 #### Formatters:
-* [black](https://black.readthedocs.io/en/stable/){:target="_blank"}
-    - Alternative: [autopep8](https://pypi.org/project/autopep8/){:target="_blank"}
-    - Alternative: [yapf](https://pypi.org/project/yapf/){:target="_blank"} 
-* [isort](https://timothycrosley.github.io/isort/){:target="_blank"} for sorting only imports in codes. This is OPTIONAL.
-
+* [black](https://black.readthedocs.io/en/stable/)
+    - Alternative: [autopep8](https://pypi.org/project/autopep8/)
+    - Alternative: [yapf](https://pypi.org/project/yapf/) 
+* [isort](https://timothycrosley.github.io/isort/) for sorting only imports in codes. This is OPTIONAL.
+    - Alternative: [reorder-python-imports](https://github.com/asottile/reorder_python_imports) another way of sorting imports.
+    
 #### Testing:
-* [pytest](https://pytest.org){:target="_blank"} with [plugins](https://docs.pytest.org/en/2.7.3/plugins_index/index.html){:target="_blank"}
+* [pytest](https://pytest.org) with [plugins](https://docs.pytest.org/en/2.7.3/plugins_index/index.html)
     - Alternative: Inbuilt `unittest`
-* [hypothesis](https://hypothesis.readthedocs.io/en/latest/){:target="_blank"} and `mock` for data generation and mocking in tests.
-* [tox](https://tox.readthedocs.io/en/latest/){:target="_blank"} for test automation in different `python` version
-    - Alternative: [nox](https://nox.thea.codes/en/stable/){:target="_blank"} is an alternative to `tox`.
+* [hypothesis](https://hypothesis.readthedocs.io/en/latest/) and `mock` for data generation and mocking in tests.
+* [tox](https://tox.readthedocs.io/en/latest/) for test automation in different `python` version
+    - Alternative: [nox](https://nox.thea.codes/en/stable/) is `tox` with `python` API i.e. py file settings so can be used if you need any dynamism.
 
 #### Other tools:
-* [coverage](https://coverage.readthedocs.io/en/coverage-5.1/){:target="_blank"} for checking code coverage of tests.
-* [interrogate](https://interrogate.readthedocs.io/en/latest/){:target="_blank"} for docstring coverage check.
-* [mypy](http://mypy-lang.org/index.html){:target="_blank"} optional static type coding with python through annotations.
+* [coverage](https://coverage.readthedocs.io/en/coverage-5.1/) for checking code coverage of tests.
+* [interrogate](https://interrogate.readthedocs.io/en/latest/) for docstring coverage check.
+* [mypy](http://mypy-lang.org/index.html) optional static type coding with python through annotations.
 
 #### Readings and References:
-* [Design Patterns](https://python-patterns.guide/){:target="_blank"}
-* [Official Documentation](https://docs.python.org/3/){:target="_blank"}
-* [Python Code Quality](https://meta.pycqa.org/en/latest/index.html){:target="_blank"} for the tools like `flake8`, `pylint`, `bandit` etc along with others.
-* [Python Packages](https://www.pypa.io/en/latest/){:target="_blank"}
+* [Design Patterns](https://python-patterns.guide/)
+* [Official Documentation](https://docs.python.org/3/)
+* [Python Code Quality](https://meta.pycqa.org/en/latest/index.html) for the tools like `flake8`, `pylint`, `bandit` etc along with others.
+* [Python Packages](https://www.pypa.io/en/latest/)

docusaurus.config.js

@@ -1,3 +1,4 @@
+const remarkLinks = require('remark-external-links');
 module.exports = {
   title: 'Coding Standards And Convention',
   tagline: 'Coding Standards And Convention Documentation',
@@ -87,6 +88,7 @@ module.exports = {
           homePageId: 'doc1',
           sidebarPath: require.resolve('./sidebars.js'),
           // Please change this to your repo.
+          remarkPlugins: [remarkLinks],
           editUrl:
             'https://github.com/facebook/docusaurus/edit/master/website/',
         },

package.json

@@ -9,11 +9,12 @@
     "deploy": "docusaurus deploy"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.0.0-alpha.55",
-    "@docusaurus/preset-classic": "^2.0.0-alpha.55",
+    "@docusaurus/core": "^2.0.0-alpha.56",
+    "@docusaurus/preset-classic": "^2.0.0-alpha.56",
     "classnames": "^2.2.6",
     "react": "^16.8.4",
-    "react-dom": "^16.8.4"
+    "react-dom": "^16.8.4",
+    "remark-external-links": "^6.0.0"
   },
   "browserslist": {
     "production": [
@@ -27,4 +28,4 @@
       "last 1 safari version"
     ]
   }
-}
+}