fix: use mkdocs instead of sphinx docs

* build(setup): extras_require mkdocs

* build(setup): extras_require mkdocs

- package mkdocstrings-python-legacy

* refactor: check sys.stdout.encoding once

also isort module

* docs: mkdocs

- skip_files for test files

* docs(CONTRIBUTING): mkdocs

CONTRIBUTING.md

@@ -22,3 +22,11 @@ is preferred.
 
 * Ensure all functions and classes have a PEP257 compliant docstring and the
 code is PEP8 compliant.
+
+## Documentation
+
+Install required extra docs package to setup mkdocs: `pip install -e ".[docs]"`
+
+To run built-in dev server: `mkdocs serve`
+
+To deploy documentation to github page: `mkdocs gh-deploy`

docs/changelog.md

@@ -0,0 +1 @@
+--8<-- "CHANGELOG.md"

docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

docs/css/mkdocstrings.css

@@ -0,0 +1,33 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: 4px solid rgba(230, 230, 230);
+  margin-bottom: 80px;
+}
+
+/* Don't capitalize names. */
+h5.doc-heading {
+  text-transform: none !important;
+}
+
+/* Don't use vertical space on hidden ToC entries. */
+.hidden-toc::before {
+  margin-top: 0 !important;
+  padding-top: 0 !important;
+}
+
+/* Don't show permalink of hidden ToC entries. */
+.hidden-toc a.headerlink {
+  display: none;
+}
+
+/* Avoid breaking parameters name, etc. in table cells. */
+td code {
+  word-break: normal !important;
+}
+
+/* For pieces of Markdown rendered in table cells. */
+td p {
+  margin-top: 0 !important;
+  margin-bottom: 0 !important;
+}

docs/gen_ref_nav.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+skip_files = [
+    (Path("mps_youtube") / "config.py"),
+    (Path("mps_youtube") / "mpris.py"),
+]
+skip_files.extend((Path("mps_youtube") / "test").glob("*.py"))
+for path in sorted(Path("mps_youtube").glob("**/*.py")):
+    if path in skip_files:
+        continue
+    module_path = path.with_suffix("")
+    doc_path = path.relative_to("mps_youtube").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = list(module_path.parts)
+    parts[-1] = f"{parts[-1]}.py"
+    nav[parts] = doc_path
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(module_path.parts)
+        print("::: " + ident, file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

docs/license.md

@@ -0,0 +1,3 @@
+```
+--8<-- "LICENSE"
+```

mkdocs.yml

@@ -0,0 +1,49 @@
+site_name: Yewtube
+site_description: Terminal based YouTube player and downloader.
+site_url: https://iamtalhaasghar.github.io/yewtube
+repo_url: https://github.com/iamtalhaasghar/yewtube
+repo_name: iamtalhaasghar/yewtube
+
+nav:
+- Home:
+  - Overview: index.md
+  - Changelog: changelog.md
+  - License: license.md
+- Code Reference: reference/
+- Development:
+  - Contributing: contributing.md
+
+theme:
+  name: material
+  features:
+  - navigation.tabs
+  palette:
+    scheme: slate
+    primary: teal
+    accent: purple
+
+extra_css:
+- css/mkdocstrings.css
+
+markdown_extensions:
+- admonition
+- pymdownx.emoji
+- pymdownx.magiclink
+- pymdownx.snippets:
+    check_paths: true
+- pymdownx.superfences
+- pymdownx.tabbed
+- pymdownx.tasklist
+- toc:
+    permalink: true
+
+plugins:
+- search
+- mkdocstrings:
+    watch:
+    - mps_youtube
+- gen-files:
+    scripts:
+    - docs/gen_ref_nav.py
+- literate-nav:
+    nav_file: SUMMARY.md

mps_youtube/player.py

@@ -1,22 +1,20 @@
-import os
-import sys
-import random
 import logging
 import math
-import time
+import os
+import random
 import shlex
-import subprocess
 import socket
-from urllib.error import HTTPError, URLError
+import subprocess
+import sys
+import time
 from abc import ABCMeta, abstractmethod
+from urllib.error import HTTPError, URLError
 
-
-from . import g, screen, c, streams, history, content, config, util
+from . import c, config, content, g, history, screen, streams, util
 from .commands import lastfm
-
+from .util import not_utf8_environment
 
 mswin = os.name == "nt"
-not_utf8_environment = mswin or "UTF-8" not in sys.stdout.encoding
 
 class BasePlayer:
     _playbackStatus = "Paused"

mps_youtube/players/mplayer.py

@@ -7,9 +7,9 @@ import typing as T
 
 from .. import c, config, g, paths, screen, util
 from ..player import CmdPlayer
+from ..util import not_utf8_environment
 
 mswin = os.name == "nt"
-not_utf8_environment = mswin or "UTF-8" not in sys.stdout.encoding
 
 
 class mplayer(CmdPlayer):

mps_youtube/players/mpv.py

@@ -1,18 +1,17 @@
-import os
-import sys
-import tempfile
-import subprocess
 import json
+import os
 import re
 import socket
+import subprocess
+import sys
+import tempfile
 import time
 
-from .. import g, screen, c, paths, config, util
-
+from .. import c, config, g, paths, screen, util
 from ..player import CmdPlayer
+from ..util import not_utf8_environment
 
 mswin = os.name == "nt"
-not_utf8_environment = mswin or "UTF-8" not in sys.stdout.encoding
 
 
 class mpv(CmdPlayer):

mps_youtube/util.py

@@ -1,27 +1,27 @@
-import os
-import re
-import sys
-import ctypes
-import logging
-import time
-import subprocess
 import collections
+import ctypes
+import json
+import logging
+import os
+import platform
+import re
+import subprocess
+import sys
+import time
 import unicodedata
 import urllib
-import json
-import platform
 from datetime import datetime, timezone
-
-
-from . import g, c, terminalsize, description_parser
-from .playlist import Video
-
 from importlib import import_module
 
+from . import c, description_parser, g, terminalsize
+from .playlist import Video
+
 macos = platform.system() == "Darwin"
 
 mswin = os.name == "nt"
-not_utf8_environment = mswin or "UTF-8" not in sys.stdout.encoding
+not_utf8_environment = mswin or (
+    "UTF-8" not in sys.stdout.encoding if sys.stdout.encoding else False
+)
 
 XYTuple = collections.namedtuple('XYTuple', 'width height max_results')
 

setup.py

@@ -41,6 +41,14 @@ options = dict(
             "dbus-python>=1.2.18",
             "PyGObject>=3.42.0",
         ],
+        "docs": [
+            "mkdocs-gen-files>=0.3.4",
+            "mkdocs-literate-nav>=0.4.1",
+            "mkdocs-macros-plugin>=0.6.4",
+            "mkdocs-material>=8.2.1",
+            "mkdocstrings-python-legacy>=0.2.2",
+            "mkdocstrings>=0.18.0",
+        ],
     },
     classifiers=[
         "Topic :: Utilities",