Merge pull request #50 from TrueMyst/main

Change Documentation from mkdocs to sphinx

.gitignore

@@ -4,6 +4,7 @@
 /venv
 /dist
 /build
+/docs/_build
 /media
 /.vscode
 /node_modules

.readthedocs.yml

@@ -1,14 +1,29 @@
-version: 2
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 
+# Required
+version: 2.0.0
+
+# Formats to be built
+formats:
+  - epbub
+  - pdf
+
+# Install requirements.txt using pip
+python:
+  install:
+    - method: pip
+    - requirements: docs/requirements.txt
+
+# Set the OS, Python version
 build:
   os: ubuntu-22.04
   tools:
     python: "3.10"
 
-mkdocs:
-  configuration: mkdocs.yml
-  fail_on_warning: false
 
-python:
-  install:
-    - requirements: docs/requirements.txt
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+  fail_on_warning: true

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,41 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+project = 'vscode.py'
+copyright = '2024, CodeWithSwastik'
+author = 'CodeWithSwastik'
+release = '2.0.0'
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.md': 'markdown'
+}
+
+source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'myst_parser']
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+html_logo = "../images/vscode-ext.png"
+html_title = f"{project} {release}"
+html_theme = 'furo'
+html_favicon = "../images/vscode-ext.png"
+html_static_path = ['_static']
+

docs/handbook/creating_extension.rst

@@ -0,0 +1,58 @@
+Creating your first extension
+=============================
+
+Getting Started
+----------------
+
+Create a folder and place a Python file inside it.
+
+.. image:: https://user-images.githubusercontent.com/61446939/126891766-8e408f35-ce63-48b1-8739-1361e979d351.png
+
+
+Write Extension Code
+---------------------
+
+.. code-block:: python
+
+    import vscode
+    from vscode import InfoMessage
+
+    ext = vscode.Extension(name="Test Extension")
+
+    @ext.event
+    async def on_activate():
+        vscode.log(f"The Extension '{ext.name}' has started")
+
+    @ext.command()
+    async def hello_world(ctx):
+        return await ctx.show(InfoMessage(f"Hello World from {ext.name}"))
+
+    ext.run()
+
+Run the Python File
+--------------------
+
+Execute the Python file. This action will build the necessary files.
+
+.. image:: https://user-images.githubusercontent.com/61446939/126891865-fe235598-9267-47c6-971f-43e4da456ebb.png
+.. image:: https://user-images.githubusercontent.com/61446939/126891875-62c2057e-e504-4e01-bfd6-9a20c7f660d9.png
+
+Run the Extension
+------------------
+
+Press F5. This will initiate the extension and open a new VSCode window in development mode.
+
+Test Your Command
+------------------
+
+- Open the command palette in the development window with `Ctrl+P`.
+
+  .. image:: https://user-images.githubusercontent.com/61446939/126892044-f3b5f4d3-37de-4db5-acef-c6ddd841f1a5.png
+
+- Type ``>Hello World`` in the command palette.
+
+  .. image:: https://user-images.githubusercontent.com/61446939/126892096-9fc1cb2f-9b76-4d53-8099-e74d9f22e6e7.png
+
+- The popup message should appear in the bottom right corner.
+
+  .. image:: https://user-images.githubusercontent.com/61446939/126892110-f8d4bcf2-9ec0-43c2-a7d6-40288d91f000.png

docs/handbook/index.rst

@@ -0,0 +1,9 @@
+Getting Started
+===============
+
+.. toctree::
+  :maxdepth: 2
+
+  installation
+  creating_extension
+  publishing_extension

docs/handbook/installation.rst

@@ -0,0 +1,38 @@
+Installation
+=============
+You may use pip or a similar tool to install latest version of **vscode.py**  from the PyPi. 
+
+Install with pip
+-----------------
+.. warning::
+
+   This module requires Python 3.6 or above to work properly.
+
+The latest stable release of **vscode.py** can be installed with pip
+
+.. code-block::
+   
+   # Linux/macOS
+   python3 -m pip install vscode.py
+
+   # Windows
+   py -3 -m pip install vscode.py
+
+However if you want the latest working version from github you can do that as well
+
+.. code-block::
+
+   # Linux/macOS
+   python3 -m pip git+https://github.com/codewithswastik/vscode.py.git
+
+   # Windows
+   py -3 -m pip install git+https://github.com/codewithswastik/vscode.py.git
+
+
+Install with git 
+-----------------
+**vscode.py** can be directly used from GitHub by cloning the repository which might be useful if you want to use the working version
+
+.. code-block::
+
+   git clone https://github.com/codewithswastik/vscode.py.git

docs/handbook/publishing_extension.rst

@@ -0,0 +1,15 @@
+Publishing Extensions
+=====================
+
+To publish your extension created with ``vscode.py``, execute your extension file with the ``--publish`` flag:
+
+.. code-block:: bash
+
+    python extension.py --publish
+
+This command will generate the ``README.md`` and ``CHANGELOG.md`` for your extension. Keeping these files updated is important. Additionally, it will create the `.vscodeignore` file. The contents specified in this file will be excluded from packaging in your extension.
+
+Afterward, follow the steps outlined in the `official documentation for publishing extensions`_.
+
+
+.. _official documentation for publishing extensions: https://code.visualstudio.com/api/working-with-extensions/publishing-extension