Merge pull request #3 from sarnold/cleanup

cleanup docs and project bits

Author: sarnold

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       #- id: check-symlinks
       - id: debug-statements
       #- id: requirements-txt-fixer
-      - id: check-executables-have-shebangs
+      #- id: check-executables-have-shebangs
       - id: check-shebang-scripts-are-executable
       - id: fix-encoding-pragma
         args: ['--remove']

README.rst

@@ -14,9 +14,10 @@ per `setuptools documentation`_.
 To use this template, replace the example project name with your own:
 
 * change the project name at the top of ``pyproject.toml``
+* change the project name in ``docs/source/conf.py`` *and* ``docs/source/index.rst``
+* change the author details in ``pyproject.toml`` *and* ``docs/source/conf.py``
 * change the package directory name under the ``src`` folder
 * change the github URL paths in ``pyproject.toml``
-* change the project name in ``docs/source/conf.py``
 
 
 .. _setuptools documentation: https://setuptools.pypa.io/en/latest/userguide/package_discovery.html
@@ -69,8 +70,8 @@ project URL below (using your new project name) and add the following new labels
 Github best practices
 ---------------------
 
-Finally, best practices for public repositories includes following extra
-features:
+Finally, best practices for public repositories should include the following
+extra features:
 
 * under Advanced Security enable Code Scanning, Dependabot, Private
   Vulnerability Reporting, and (default) Codeql config
@@ -157,7 +158,8 @@ types and line numbers. Note you must fix any fatal errors for the
 commit to succeed; some errors should be fixed automatically (use
 ``git status`` and ``git diff`` to review any changes).
 
-See the following sections for more information on gitchangelog and pre-commit.
+See the following sections in the built docs for more information on
+gitchangelog and pre-commit.
 
 You will need to install pre-commit before contributing any changes;
 installing it using your system's package manager is recommended,

docs/source/README.rst

@@ -0,0 +1 @@
+../../README.rst

docs/source/conf.py

@@ -12,16 +12,16 @@
 
 # -- Project information -----------------------------------------------------
 
-proj_name = 'ds2mermaid'
+proj_name = 'simple'
 # The full version, including alpha/beta/rc tags with setuptols-scm
 # workaround for extra-long dirty version string
 release = version(proj_name).split("+")[0]
-# The short X.Y version.
-version = '.'.join(release.split('.')[:2])
+# Use dev version instead of short X.Y version.
+version = release
 
 project = proj_name
-author = 'Goleta Star, LLC'
-copyright = '2022 - ' + str(datetime.now().year) + f' {author}'
+author = 'Tracy Developer'
+copyright = str(datetime.now().year) + f' {author}'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -48,22 +48,11 @@
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
-    'recommonmark',
+    'myst_parser',
 ]
 
-# autoapi
-#autoapi_dirs = ['../../src']
-
-# API docs
-# apidoc_modules = [
-    # {
-        # "path": f"../../src/{proj_name}",
-        # "destination": "api/",
-    # },
-# ]
-
 # sphinxcontrib.apidoc
-apidoc_module_dir = '../../src'
+apidoc_module_dir = f'../../src/{project}'
 apidoc_output_dir = 'api'
 apidoc_excluded_paths = ['scripts', 'tests']
 apidoc_module_first = True
@@ -76,7 +65,10 @@
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of strings:
 #
-source_suffix = ['.rst', '.md']
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown',
+}
 
 # The master toctree document.
 master_doc = 'index'
@@ -94,19 +86,19 @@
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'data']
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = 'manni'
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-#html_theme = 'sphinx_rtd_theme'
-html_theme = 'classic'  # still has a version
+html_theme = 'sphinx_rtd_theme'
+# setup in https://sphinx-nefertiti.readthedocs.io/latest/quick-start.html
+#html_theme = 'sphinx_nefertiti'
 
 html_sidebars = {
     '**': [
@@ -135,7 +127,7 @@
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'ds2mermaiddoc'
+htmlhelp_basename = 'simpledoc'
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -162,7 +154,7 @@
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    (master_doc, 'ds2mermaid.tex', 'ds2mermaid Documentation',
+    (master_doc, 'simple.tex', 'simple Documentation',
      [author], 'manual'),
 ]
 
@@ -172,7 +164,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'ds2mermaid', 'ds2mermaid Documentation',
+    (master_doc, 'simple', 'simple Documentation',
      [author], 1)
 ]
 
@@ -183,7 +175,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'ds2mermaid', 'ds2mermaid Documentation',
-     [author], 'ds2mermaid', description,
+    (master_doc, 'simple', 'simple Documentation',
+     [author], 'simple', description,
      'Miscellaneous'),
 ]

docs/source/index.rst

@@ -1,4 +1,4 @@
-Foobar API and SW Docs
+Simple API and SW Docs
 ======================
 
 .. git_commit_detail::
@@ -10,10 +10,10 @@ Foobar API and SW Docs
     :no_github_link:
 
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 1
     :caption: Contents:
 
-    readme_include
+    README
     api/modules
     dev/generate-changelog
     dev/pre-commit-config

docs/source/readme_include.rst

@@ -6,15 +6,15 @@ requires = [
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "ds2mermaid"
-description = "A mermaid diagram generator for doorstop requirements"
+name = "simple"
+description = "A simple project template using setuptools and setuptools-scm"
 dynamic = ["version"]
 readme = "README.rst"
 license = "MIT"
 
 authors = [
-    {name = "Stephen Arnold"},
-    {email = "[email protected]"},
+    {name = "Tracy Developer"},
+    {email = "[email protected]"},
 ]
 
 classifiers = [
@@ -34,7 +34,6 @@ classifiers = [
 dependencies = [
     'importlib-resources; python_version < "3.10"',
     "munch[yaml]",
-    "platformdirs",
 ]
 
 requires-python = ">=3.9"
@@ -55,19 +54,21 @@ doc = [
     "sphinx",
     "sphinxcontrib.apidoc",
     "sphinx_git",
-    "recommonmark",
-    "sphinx_rtd_theme<3.0",
+    "myst-parser",
+    "sphinxcontrib.mermaid",
+    "sphinx_rtd_theme<3.0",  # for the version display
+    "sphinx-nefertiti",
 ]
 test = [
     "pytest",
     "pytest-cov",
 ]
 
 [project.urls]
-Homepage = "https://github.com/sarnold/doorstop-to-mermaid"
-Repository = "https://github.com/sarnold/doorstop-to-mermaid.git"
-Issues = "https://github.com/sarnold/doorstop-to-mermaid/issues"
-Changelog = "https://github.com/sarnold/doorstop-to-mermaid/blob/main/CHANGELOG.rst"
+Homepage = "https://github.com/sarnold/simple-python-project"
+Repository = "https://github.com/sarnold/simple-python-project.git"
+Issues = "https://github.com/sarnold/simple-python-project/issues"
+Changelog = "https://github.com/sarnold/simple-python-project/blob/main/CHANGELOG.rst"
 
 [tool.setuptools]
 package-dir = {"" = "src"}

pyproject.toml

@@ -1,3 +1,2 @@
 importlib-resources; python_version < "3.10"
 munch[yaml]
-platformdirs

requirements.txt

@@ -4,7 +4,7 @@
 
 from importlib.metadata import version
 
-__version__ = version('ds2mermaid')
+__version__ = version('simple')
 
 __all__ = [
     "__version__",

src/ds2mermaid/__init__.py src/simple/__init__.pysrc/ds2mermaid/__init__.py renamed to src/simple/__init__.py

@@ -1,10 +1,9 @@
 from pathlib import Path
 
+import pytest
 from munch import Munch
 
-from ds2mermaid import version
-
-import pytest
+from simple import version
 
 
 def test_nothing(capfd):