Merge pull request #21 from UniversalPython/add-docs

docs: add UniversalPython docs

Author: haroon10725

_static/tut_chap2.png

@@ -14,7 +14,9 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = [
+    "sphinx_copybutton",
+]
 
 templates_path = ['_templates']
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

conf.py

@@ -6,12 +6,42 @@
 UniversalPython documentation
 =============================
 
-Add your content using ``reStructuredText`` syntax. See the
-`reStructuredText <https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
-documentation for details.
+Welcome! This is the official documentation for UniversalPython.
+
+**Documentation sections:**
+
+.. raw:: html
+
+   <div style="display: flex; flex-wrap: wrap; gap: 30px; margin-top: 1em; padding-left: 2em;">
+
+      <div style="flex: 1 1 calc(50% - 50px); min-width: 200px;">
+         <p style="margin-top: 0;">
+            <a href="tutorial.html">Tutorial</a><br>
+            <em>Start here: a tour of UniversalPython syntax and features</em>
+         </p>
+      </div>
+
+      <div style="flex: 1 1 calc(50% - 50px); min-width: 200px;">
+         <p style="margin-top: 0;">
+            <a href="supported_languages.html">Supported Languages</a><br>
+            <em>Checkout the supported languages in UniversalPython</em>
+         </p>
+      </div>
+
+      <div style="flex: 1 1 calc(50% - 50px); min-width: 200px;">
+         <p style="margin-top: 0;">
+            <a href="try_it_yourself.html">Try it Yourself</a><br>
+            <em>Try UniversalPython in your browser. No installs needed.</em>
+         </p>
+      </div>
+
+   </div>
 
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :hidden:
 
+   tutorial
+   supported_languages
+   try_it_yourself

index.rst

@@ -0,0 +1,56 @@
+Supported Languages
+===================
+
+UniversalPython lets you write Python code using your preferred human language! While Python is the programming language behind the scenes, UniversalPython is a transpiler which supports writting Python code in multiple natural languages.
+
+This allows developers worldwide to code in Python using the language they feel most comfortable with.
+
+Supported Human Languages
+-------------------------
+
+- English
+  *Extension:* \[placeholder for English language extension\]
+- Urdu
+  *Extension:* \[placeholder for Urdu language extension\]
+- Hindi
+  *Extension:* \[placeholder for Hindi language extension\]
+- Spanish
+  *Extension:* \[placeholder for Spanish language extension\]
+- ...and more to come!
+
+How It Works
+------------
+
+You write your UniversalPython programs using localized Python syntax in your chosen language. UniversalPython translates your code internally into standard Python, which is then executed as usual.
+
+Example
+-------
+
+Here is a simple function written in English and French versions:
+
+English:
+
+.. code-block:: python
+   :linenos:
+
+    def hello():     
+        print("Hello, UniversalPython!")
+
+    hello()
+
+French:
+
+.. code-block:: python
+   :linenos:
+
+    déf hello():     
+        imprimer("Hello, UniversalPython!")
+
+    hello()
+
+Next Steps
+----------
+
+For details on how to install and use language extensions, visit the corresponding language’s documentation page.
+
+If you want to contribute translations or help improve UniversalPython’s language support, check out the Community page.

supported_languages.rst

@@ -0,0 +1,11 @@
+Try it yourself
+===============
+
+Want to experience UniversalPython without installing anything? Use our `Online Playground <https://universalpython.github.io/playground/>`_ to write and run Python code in your preferred language directly in the browser.
+
+What You Can Do
+---------------
+
+- Write UniversalPython code using supported languages
+- Instantly run code and see output
+- Use pre-configured examples or write your own code

try_it_yourself.rst

@@ -0,0 +1,58 @@
+What is UniversalPython
+========================
+
+UniversalPython is a **transpiler** that allows you to write Python code using keywords and identifiers in your **native human language**.
+
+It is not a new language, nor a fork of **Python**. It is a thin compatibility layer that translates code written with localized keywords into **standard** **Python**. Your code is executed by the **official** **Python** **interpreter**, and behaves just like any other Python program.
+
+The goal of UniversalPython is to make programming in Python more accessible, especially for beginners and students learning in non-English environments.
+
+Transpiler, Not Interpreter
+---------------------------
+
+UniversalPython works by **transpiling** code that is, converting it from one form (Python written in a different human language) to another (standard Python source code), before running it.
+
+This means:
+
+- You are still writing **real Python code**
+- Your code will work with **standard Python tools, libraries, and environments**
+- The result is indistinguishable from code written in standard Python
+
+Why This Matters for Learners
+-----------------------------
+
+Python is one of the most widely used languages in education. However, Python's syntax, although simple, is still written in English.
+
+For many learners (who are not from English speaking countries), especially young students or those new to programming, the English vocabulary can be a barrier. **UniversalPython** helps reduce that barrier by translating code to and from the learner’s own language.
+
+This allows learners to focus on **logic and structure**, not foreign keywords.
+
+For example, a French learner might write:
+
+.. code-block:: text
+   :linenos:
+   
+    something = 2
+
+    si something == 1:
+      imprimer ("Hello")
+    sinonsi something == 2:
+      imprimer ("World")
+    sinon:
+      imprimer ("Didn't understand...")
+
+Python will understand it as:
+
+.. code-block:: python
+   :linenos:
+
+    something = 2
+
+    if something == 1:
+      print("Hello")
+    elif something == 2:
+      print("World")
+    else:
+      print("Didn't understand...")
+
+

tut_chap1.rst

@@ -0,0 +1,24 @@
+Using Your Native Language
+==========================
+
+UniversalPython supports writing Python code with keywords and standard library functions translated into your native language.
+
+Supported Languages and Extensions
+----------------------------------
+
+UniversalPython supports multiple languages through language-specific extensions.
+
+For example:
+
+- English (default, no extension needed)
+- French (`<filename>.fr.py`)
+- Chinese (`<filename>.zh.py`)
+- German (`<filename>.de.py`)
+- And many more (see the full list in the **Supported Languages** section)
+
+Each language extension provides the necessary translations for Python keywords, built-in functions, and standard library aliases.
+
+.. image:: _static/tut_chap2.png
+   :alt: ""
+   :width: 100%
+   :align: center

tut_chap2.rst

@@ -0,0 +1,20 @@
+Your First Program
+==================
+
+Programming may seem intimidating at first, but it really starts with just a few words and one good idea.
+
+In this tutorial, you’ll write your first real Python program using UniversalPython. You’ll use familiar, everyday language to tell the computer what to do.
+
+You don’t need to understand everything right away. Just follow the steps and see what happens!
+
+.. important::
+
+    If you haven’t set up UniversalPython yet, go to the Setup section first, then come back here when you're ready.
+
+**1. Create the File**
+
+Open your text editor and create a new file.
+
+If you're using French, save the file as: ``main.fr.py``
+
+The file extension (like ``.fr.py``) tells UniversalPython which language you're writing in. (In this case, French)

tut_chap3.rst

@@ -0,0 +1,34 @@
+Tutorial
+========
+
+.. tip::
+    This tutorial introduces you to UniversalPython, a tool that helps learners write Python code using keywords and identifiers in their native human language.
+
+
+This tutorial introduces you to **UniversalPython**, a tool that helps learners write Python code using keywords and identifiers in their **native human language**.
+
+UniversalPython is **not a new language**. It is a **transpiler**, a small layer that translates code written in other natural languages into standard Python. This allows students to begin learning Python concepts using familiar vocabulary.
+
+All code written in UniversalPython is executed as **real Python**. You can use the full Python standard library and any third-party packages. The goal of UniversalPython is to **lower the language barrier**, not to replace or redefine Python.
+
+This tutorial is written for:
+
+- Learners who want to explore Python in their own language
+- Teachers who want to introduce programming without the barrier of English syntax
+
+To follow this tutorial, you will need:
+
+- Python 3.4 or later
+- A Terminal or Jupiter Notebook
+- Optionally, access to the `Online Playground <https://universalpython.github.io/playground/>`_ for running code in the browser
+
+We recommend reading the tutorial chapters in order. However, if you are already familiar with Python and only want to understand UniversalPython’s features, you may skip ahead to the Using Your Native Language in Python chapter.
+
+**Chapters:**
+
+.. toctree::
+   :maxdepth: 1
+
+   tut_chap1
+   tut_chap2
+   tut_chap3