Merge pull request #2 from CarliJoy/badges

Improve Documentation

Author: CarliJoy

.gitignore

@@ -43,8 +43,10 @@ sdist/*
 docs/api/*
 docs/_rst/*
 docs/_build/*
+docs/README.rst
 cover/*
 MANIFEST
 
 # Per-project virtualenvs
 .venv*/
+

.readthedocs.yml

@@ -0,0 +1,10 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  version: 3.8
+  install:
+    - requirements: docs/requirements.txt

AUTHORS.rst

@@ -2,4 +2,4 @@
 Contributors
 ============
 
-* Carli <Carl.Freudenberg@enercon.de>
+* Carli* Freudenberg <kound@posteo.de>

CHANGELOG.rst

@@ -2,9 +2,15 @@
 Changelog
 =========
 
-Version 0.1
-===========
+Version 0.0.2
+=============
+- Documentation Only Changes
+    - Add Badges
+    - Import Readme to documentation
+    - Allow build of documentation even without pywin32 installed
+    - Use ReadTheDoc Sphinx Theme
 
-- Feature A added
-- FIX: nasty bug #1729 fixed
-- add your changes here!
+Version 0.0.1
+=============
+
+- First Release

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 Carli
+Copyright (c) 2020 Carli* Freudenberg
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,3 +1,11 @@
+[![Build Status](https://travis-ci.org/CarliJoy/SyncGitlab2MSProject.svg?branch=master)](https://travis-ci.org/CarliJoy/SyncGitlab2MSProject)
+[![](https://img.shields.io/pypi/v/SyncGitlab2MSProject.svg)](https://pypi.org/project/SyncGitlab2MSProject/)
+[![](https://img.shields.io/pypi/pyversions/SyncGitlab2MSProject.svg)](https://pypi.org/project/SyncGitlab2MSProject/)
+[![](https://img.shields.io/pypi/wheel/SyncGitlab2MSProject.svg)](https://pypi.org/project/SyncGitlab2MSProject/)
+[![](https://img.shields.io/pypi/status/SyncGitlab2MSProject.svg)](https://pypi.org/project/SyncGitlab2MSProject/)
+[![Code Style Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 # SyncGitlab2MSProject
 
 Sync Gitlab Issues with a Microsoft Project File.
@@ -26,6 +34,11 @@ group. Problem is that accessing issues only by ID is just allowed for admins.
 ## Requirements
 This project runs only in an Windows Environment with Microsoft Project installed.
 
+**Please note:** This Script has been tested only mit Microsoft Project 2016.
+It cloud be, that some of the API has changed in newer versions. 
+If you run into any troubles with a new version, please open an 
+[Issue](https://github.com/CarliJoy/SyncGitlab2MSProject/issues/new). 
+ 
 ## Usage
 ```
 usage: sync_gitlab2msproject [-h] [--version] [-v] [-vv] [--gitlab-url GITLAB_URL] [--gitlab-token GITLAB_TOKEN] {project,group} gitlab_resource_id project_file

docs/conf.py

@@ -13,13 +13,26 @@
 import inspect
 import shutil
 
-__location__ = os.path.join(os.getcwd(), os.path.dirname(
-    inspect.getfile(inspect.currentframe())))
+__location__ = os.path.join(
+    os.getcwd(), os.path.dirname(inspect.getfile(inspect.currentframe()))
+)
+
+import m2r2
+
+readme_rst_content = m2r2.parse_from_file(os.path.join(__location__, "..", "README.md"))
+with open(os.path.join(__location__, "README.rst"), "w") as f:
+    f.write(readme_rst_content)
+
+# Try to import win32com, otherwise use mocking
+try:
+    import win32com
+except ImportError:
+    sys.path.insert(0, os.path.join(__location__, "../mocking"))
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.join(__location__, '../src'))
+sys.path.insert(0, os.path.join(__location__, "../src"))
 
 # -- Run sphinx-apidoc ------------------------------------------------------
 # This hack is necessary since RTD does not issue `sphinx-apidoc` before running
@@ -49,7 +62,7 @@
     cmd_line = cmd_line_template.format(outputdir=output_dir, moduledir=module_dir)
 
     args = cmd_line.split(" ")
-    if parse_version(sphinx.__version__) >= parse_version('1.7'):
+    if parse_version(sphinx.__version__) >= parse_version("1.7"):
         args = args[1:]
 
     apidoc.main(args)
@@ -63,48 +76,64 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo',
-              'sphinx.ext.autosummary', 'sphinx.ext.viewcode', 'sphinx.ext.coverage',
-              'sphinx.ext.doctest', 'sphinx.ext.ifconfig', 'sphinx.ext.mathjax',
-              'sphinx.ext.napoleon']
-extensions.append('recommonmark')
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.coverage",
+    "sphinx.ext.doctest",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.napoleon",
+    "sphinx_rtd_theme",
+    "recommonmark",
+]
+
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 
 # To configure AutoStructify
 def setup(app):
     from recommonmark.transform import AutoStructify
-    app.add_config_value('recommonmark_config', {
-        'auto_toc_tree_section': 'Contents',
-        'enable_eval_rst': True,
-        'enable_math': True,
-        'enable_inline_math': True
-    }, True)
+
+    app.add_config_value(
+        "recommonmark_config",
+        {
+            "auto_toc_tree_section": "Contents",
+            "enable_eval_rst": True,
+            "enable_math": True,
+            "enable_inline_math": True,
+        },
+        True,
+    )
     app.add_transform(AutoStructify)
 
+
 # The suffix of source filenames.
-source_suffix = ['.rst', '.md']
+source_suffix = [".rst", ".md"]
 
 # The encoding of source files.
 # source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = 'index'
+master_doc = "index"
 
 # General information about the project.
-project = u'SyncGitlab2MSProject'
-copyright = u'2020, Carli'
+project = u"SyncGitlab2MSProject"
+copyright = u"2020, Carli* Freudenberg"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = ''  # Is set by calling `setup.py docs`
+version = ""  # Is set by calling `setup.py docs`
 # The full version, including alpha/beta/rc tags.
-release = ''  # Is set by calling `setup.py docs`
+release = ""  # Is set by calling `setup.py docs`
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -118,7 +147,7 @@ def setup(app):
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build']
+exclude_patterns = ["_build"]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 # default_role = None
@@ -135,7 +164,7 @@ def setup(app):
 # show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # A list of ignored prefixes for module index sorting.
 # modindex_common_prefix = []
@@ -148,15 +177,12 @@ def setup(app):
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = "sphinx_rtd_theme"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-html_theme_options = {
-    'sidebar_width': '300px',
-    'page_width': '1200px'
-}
+html_theme_options = {"sidebar_width": "300px", "page_width": "1200px"}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -185,7 +211,7 @@ def setup(app):
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -229,27 +255,30 @@ def setup(app):
 # html_file_suffix = None
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'syncgitlab2msproject-doc'
+htmlhelp_basename = "syncgitlab2msproject-doc"
 
 
 # -- Options for LaTeX output --------------------------------------------------
 
 latex_elements = {
-# The paper size ('letterpaper' or 'a4paper').
-# 'papersize': 'letterpaper',
-
-# The font size ('10pt', '11pt' or '12pt').
-# 'pointsize': '10pt',
-
-# Additional stuff for the LaTeX preamble.
-# 'preamble': '',
+    # The paper size ('letterpaper' or 'a4paper').
+    # 'papersize': 'letterpaper',
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '10pt',
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'user_guide.tex', u'SyncGitlab2MSProject Documentation',
-   u'Carli', 'manual'),
+    (
+        "index",
+        "user_guide.tex",
+        u"SyncGitlab2MSProject Documentation",
+        u"Carli",
+        "manual",
+    ),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -273,13 +302,13 @@ def setup(app):
 # latex_domain_indices = True
 
 # -- External mapping ------------------------------------------------------------
-python_version = '.'.join(map(str, sys.version_info[0:2]))
+python_version = ".".join(map(str, sys.version_info[0:2]))
 intersphinx_mapping = {
-    'sphinx': ('http://www.sphinx-doc.org/en/stable', None),
-    'python': ('https://docs.python.org/' + python_version, None),
-    'matplotlib': ('https://matplotlib.org', None),
-    'numpy': ('https://docs.scipy.org/doc/numpy', None),
-    'sklearn': ('http://scikit-learn.org/stable', None),
-    'pandas': ('http://pandas.pydata.org/pandas-docs/stable', None),
-    'scipy': ('https://docs.scipy.org/doc/scipy/reference', None),
-}
+    "sphinx": ("http://www.sphinx-doc.org/en/stable", None),
+    "python": ("https://docs.python.org/" + python_version, None),
+    "matplotlib": ("https://matplotlib.org", None),
+    "numpy": ("https://docs.scipy.org/doc/numpy", None),
+    "sklearn": ("http://scikit-learn.org/stable", None),
+    "pandas": ("http://pandas.pydata.org/pandas-docs/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
+}

docs/index.rst

@@ -4,24 +4,7 @@ SyncGitlab2MSProject
 
 This is the documentation of **SyncGitlab2MSProject**.
 
-.. note::
-
-    This is the main page of your project's `Sphinx`_ documentation.
-    It is formatted in `reStructuredText`_. Add additional pages
-    by creating rst-files in ``docs`` and adding them to the `toctree`_ below.
-    Use then `references`_ in order to link them from this page, e.g.
-    :ref:`authors` and :ref:`changes`.
-
-    It is also possible to refer to the documentation of other Python packages
-    with the `Python domain syntax`_. By default you can reference the
-    documentation of `Sphinx`_, `Python`_, `NumPy`_, `SciPy`_, `matplotlib`_,
-    `Pandas`_, `Scikit-Learn`_. You can add more by extending the
-    ``intersphinx_mapping`` in your Sphinx's ``conf.py``.
-
-    The pretty useful extension `autodoc`_ is activated by default and lets
-    you include documentation from docstrings. Docstrings can be written in
-    `Google style`_ (recommended!), `NumPy style`_ and `classical style`_.
-
+.. include:: README.rst
 
 Contents
 ========

docs/requirements.txt

@@ -0,0 +1,4 @@
+sphinx-rtd-theme>=0.5.0
+Sphinx>=3.3.1
+recommonmark>=0.6.0
+m2r2>=0.2.5

mocking/README.md

@@ -0,0 +1,7 @@
+# About this directory
+
+This directory contains mocks for pywin32 classes.
+It is used so that the documentation can build on non Windows operating system
+like Linux.
+
+**DON'T EXPECT ANY FUNCTIONALITY HERE!!**