Feature v2

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: test-${{ github.head_ref }}
+  cancel-in-progress: true
+
+env:
+  PYTHONUNBUFFERED: "1"
+  FORCE_COLOR: "1"
+
+jobs:
+  run:
+    name: Python ${{ matrix.python-version }} on ${{ startsWith(matrix.os, 'macos-') && 'macOS' || startsWith(matrix.os, 'windows-') && 'Windows' || 'Linux' }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.12']
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install Hatch
+        run: pip install --upgrade hatch
+      - name: Run tests
+        run: hatch run test
+      - name: Upload Codecov Results
+        if: success()
+        uses: codecov/codecov-action@v3
+        with:
+          file: lcov.info

.github/workflows/docs.yml

@@ -0,0 +1,25 @@
+name: Documentation
+on:
+  push:
+    branches: [main]
+    tags: ['*']
+permissions:
+  contents: write
+jobs:
+  deploy:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+      - name: Install Hatch
+        run: pip install --upgrade hatch
+      - name: Deploy documentation
+        run: hatch run docs:deploy

.gitignore

@@ -1,17 +1,74 @@
-*.pyc
+# Byte-compiled / optimized / DLL files
 __pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
 build/
+develop-eggs/
 dist/
-*.egg-info/
+downloads/
+eggs/
 .eggs/
-.coverage.*
-.coverage
+lib/
+lib64/
+node_modules/
+parts/
+sdist/
+var/
+package*.json
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
 htmlcov/
-.ropeproject/
-.pytest_cache/
-.mypy_cache/
-tests/docs/site/
-.pheasant_cache/
-notebooks/
-.env/
-.venv/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*,cover
+.hypothesis/
+
+# Translations
+*.mo
+
+# Scrapy stuff:
+.scrapy
+
+# PyBuilder
+target/
+
+# IPython Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# virtualenv
+venv/
+ENV/
+
+# MkDocs documentation
+site*/
+examples/docs/api
+examples/docs/api2
+
+lcov.info

LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2020-present daizutabi <daizutabi@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -1,23 +1,30 @@
+# MkAPI
+
 [![PyPI version][pypi-image]][pypi-link]
 [![Python versions][pyversions-image]][pyversions-link]
-[![Travis][travis-image]][travis-link]
-[![AppVeyor][appveyor-image]][appveyor-link]
-[![Coverage Status][coveralls-image]][coveralls-link]
 [![Code style: black][black-image]][black-link]
 
-# MkApi
+MkAPI plugin for [MkDocs](https://www.mkdocs.org/) generates
+API documentation for Python code.
 
-MkApi plugin for [MkDocs](https://www.mkdocs.org/) generates API documentation for Python code. MkApi supports two styles of docstrings: [Google](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) and [NumPy](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
+MkAPI supports two styles of docstrings:
+[Google](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) and
+[NumPy](https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard).
 
-Features of MkApi are:
+Features of MkAPI are:
 
-* **Type annotation**: If you write your function such as `def func(x: int) -> str:`, you don't need write type(s) in Parameters, Returns, or Yields section again. You can overwrite the type annotation in the corresponding docstring.
-* **Object type inspection**: MkApi plugin creates *class*, *dataclass*, *function*, or *generator* prefix for each object.
-* **Attribute inspection**: If you write attributes with description as comment in module or class, Attributes section is automatically created.
-* **Docstring inheritance**: Docstring of a subclass can inherit parameters and attributes description from its superclasses.
-* **Table of Contents**: Table of contents are inserted into the documentation of each package, module, and class.
-* **Page mode**: Comprehensive API documentation for your project, in which objects are linked to each other by type annotation.
-* **Bidirectional Link**: Using the Page mode, bidirectional links are created between documentation and source code.
+* **Type annotation**: If you write your function such as
+  `def func(x: int) -> str:`, you don't need write type(s)
+  in Parameters, Returns, or Yields section again.
+  You can overwrite the type annotation in the corresponding docstring.
+* **Object type inspection**: MkAPI plugin creates *class*,
+  *dataclass*, *function*, *method*, *property* prefix for each object.
+* **Docstring inheritance**: Docstring of a subclass can inherit parameters
+  and attributes description from its superclasses.
+* **Table of Contents**: Table of contents are inserted into the documentation
+  of each package, module, and class.
+* **Bidirectional Link**: Bidirectional links are created between
+  documentation and source code.
 
 ## Installation
 
@@ -33,64 +40,53 @@ Add the following lines to `mkdocs.yml`:
 
 ~~~yml
 plugins:
-  - search # necessary for search to work
   - mkapi
 ~~~
 
 ## Usage
 
-MkApi provides two modes to generate API documentation: Embedding mode and Page mode.
+MkAPI provides two modes to generate API documentation:
+Object mode and Page mode.
 
-### Embedding Mode
+### Object Mode
 
-To generate the API documentation in a Markdown source, add an exclamation mark (!), followed by `mkapi` in brackets, and the object full name in parentheses. Yes, this is like adding an image. The object can be a function, class, or module.
+To generate the API documentation in a Markdown source,
+add three colons + object full name.
+The object can be a function, class, attribute, or module.
 
 ~~~markdown
-![mkapi](<package.module.object>)
+::: package.module.object
 ~~~
 
 You can combine this syntax with Markdown heading:
 
 ~~~markdown
-## ![mkapi](<package.module.object>)
+## ::: package.module.object
 ~~~
 
-MkApi imports objects that you specify. If they aren't in the `sys.path`, configure `mkdocs.yml` like below:
-
-~~~yml
-plugins:
-  - search
-  - mkapi:
-      src_dirs: [<path1>, <path2>, ...]
-~~~
-
-Here, `pathX`s are inserted to `sys.path`. These `pathX`s must be relative to the `mkdocs.yml` directory.
-
-The embedding mode is useful to embed an object interface in an arbitrary position of a Markdown source. For more details, see:
+The embedding mode is useful to embed an object interface
+in an arbitrary position of a Markdown source. For more details, see:
 
 * [Google style examples](https://mkapi.daizutabi.net/examples/google_style)
 * [NumPy style examples](https://mkapi.daizutabi.net/examples/numpy_style)
 
 ### Page Mode
 
-Using the page mode, you can construct a comprehensive API documentation for your project. You can get this powerful feature by just one line:
+Using the page mode, you can construct a comprehensive API documentation
+for your project.
+You can get this powerful feature by just one line:
 
 ~~~yaml
 nav:
   - index.md
-  - API: mkapi/api/mkapi
+  - API: <api>/mkapi.***
 ~~~
 
-For more details, see [Page Mode and Internal Links](https://mkapi.daizutabi.net/usage/page)
+For more details, see
+[Page mode and internal links](https://mkapi.daizutabi.net/usage/page)
 
 [pypi-image]: https://badge.fury.io/py/mkapi.svg
 [pypi-link]: https://pypi.org/project/mkapi
-[travis-image]: https://travis-ci.org/daizutabi/mkapi.svg?branch=master
-[travis-link]: https://travis-ci.org/daizutabi/mkapi
-[appveyor-image]: https://ci.appveyor.com/api/projects/status/ys2ic8n4j7r5j4bg/branch/master?svg=true
-[appveyor-link]: https://ci.appveyor.com/project/daizutabi/mkapi
-[coveralls-image]: https://coveralls.io/repos/github/daizutabi/mkapi/badge.svg?branch=master
-[coveralls-link]: https://coveralls.io/github/daizutabi/mkapi?branch=master
 [black-image]: https://img.shields.io/badge/code%20style-black-000000.svg
 [black-link]: https://github.com/ambv/black
 [pyversions-image]: https://img.shields.io/pypi/pyversions/mkapi.svg