Merge pull request #17 from Catenscia/develop

Develop

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: EtienneWallet
+
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## To Reproduce
+
+Steps to reproduce the behavior:
+
+1. Give your python and MxOps versions
+2. Show the code / files you tried to execute
+3. Show the full error / bug obtained
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Screenshots
+
+If applicable, add screenshots to help explain your problem.
+
+## Additional context
+
+Add any other context about the problem here.

.gitignore

@@ -1,3 +1,7 @@
+# MxOps related files
+
+mxops_config.ini
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]

.pylintrc

@@ -0,0 +1,5 @@
+[MESSAGES CONTROL]
+disable=W1203
+
+[FORMAT]
+good-names=tx

CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing to MxOps
+
+:+1::tada: First off, thanks for taking the time to contribute! :tada::+1:
+
+The following is a set of guidelines for contributing to the MxOps package which is hosted by the [Catenscia Organization](https://github.com/Catenscia) on Github. These are mostly guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.
+
+## Reporting an issue
+
+If you encountered an issue or a bug, don't hesitate to write a detailed issue in the repo. the guidelines are [here](./.github/ISSUE_TEMPLATE/bug_report.md)
+
+## Submitting changes
+
+If you fixed an issue or implemented a new feature, please send a pull request with a clear list of what you've done and make sure all of your commits are atomic
+(one feature per commit).
+Always write a clear log message for your commits.
+
+Please follow this steps:
+
+- Fork this repo
+- create a new branch from `develop`
+- make your changes and commits continuously to your branch
+- submit a PR from your branch to the `develop` branch of this repo
+
+## Branch names
+
+Banches names should reflect the type of change they bring.
+The examples below should fit most needs.
+
+| **Change type** | Description                                            | Name                       |
+|-----------------|--------------------------------------------------------|----------------------------|
+| **Feature**     | For any feature that will be added to the project      | `feature_<feature_name>`   |
+| **Fix**         | For any bug fix on the project                         | `fix_<bug_name>`           |
+| **Refactor**    | For any change that do not impact the functionnalities | `refactor_<refactor_name>` |
+| **Test**        | For any test(s) that will be added to the project      | `test_<test_name>`         |
+
+Many thanks! :heart: :heart: :heart:

README.md

@@ -1,2 +1,23 @@
-# xOps
-Python package to automate MultiversX smart contracts deployments and interactions in general
+# MxOps
+
+MxOps is a python package created to automate MultiversX smart contracts deployments, calls and querys.
+Inspired from DevOps tools, it aims to ease and make reproductible any set of these interactions with smart-contracts.
+
+MxOps aims to be useful in these situations:
+
+- deployment automation
+- on-chain integration tests
+- contract interaction automation
+
+## Get Started
+
+Heads up to the quickstart in the [documentation](https://mxops.readthedocs.io) to get started!
+
+## Contribution
+
+This tool is an humble proposal by [Catenscia](https://catenscia.com/) to have a standard way of writing deployment files, integrations tests and others.
+If you want this tool to improve, please tell us your issues and proposals!
+
+And if you're motivated, we will always welcome hepling hands onboard :grin: !
+
+Read the [contribution guidelines](./CONTRIBUTING.md) for more :wink:

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     = source
+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/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,44 @@
+# 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
+import os
+import re
+
+# -- Retrieve the version from pyproject.toml -------------------------------
+this_directory = os.path.abspath(os.path.dirname(__file__))
+about = {}
+with open(os.path.join(this_directory, '../../pyproject.toml'), encoding='utf-8') as file:
+    content = file.read()
+
+version_pattern = '\nversion\s*=\s*"(.*)"\n'
+pattern_match = re.search(version_pattern, content)
+if pattern_match is None:
+    raise RuntimeError("Could not retrieve the version from pyproject.toml")
+version_string = pattern_match.groups(0)[0]
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'MxOps'
+copyright = '2023, Catenscia'
+author = 'Catenscia'
+release = version_string
+version = version_string
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = ["myst_parser"]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+

docs/source/dev_documentation/backlog.md

@@ -0,0 +1,10 @@
+# Backlog
+
+- [ ] Add an optional delay before/after each step
+- [ ] Create a framework to allow a user to create a step which will execute any custom made python functions. (This would allow extreme customizations for users)
+- [ ] Add Keystore support
+- [ ] Add Maiar support
+- [ ] Add a specific step for contract ownership transfer.
+- [ ] Add a skip keyword to skip steps without deleting them
+- [ ] Add querry and call support for external contracts
+- [ ] Add configurable transactions contents checks (transfers, data, results...)

docs/source/dev_documentation/changelog.md

@@ -0,0 +1,19 @@
+# ChangeLog
+
+## Unreleased
+
+### Added
+
+- None
+
+### Changed
+
+- None
+
+### Removed
+
+- None
+
+## 0.1.0 - 2023-01-23
+
+First version of MxOps.

docs/source/index.rst

@@ -0,0 +1,30 @@
+.. MxOps documentation master file, created by
+   sphinx-quickstart on Mon Jan 23 13:36:05 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to MxOps |version| !
+=========================================
+
+You are in the MxOps documentation. Use the left-side pannel or the menu below to navigate where you want to go.
+If you are new here, we recommand going first to the :doc:`user_documentation/overview` section and then to the :doc:`user_documentation/getting_started`.
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Documentation
+
+   user_documentation/overview
+   user_documentation/getting_started
+   user_documentation/scenario
+   user_documentation/scenes
+   user_documentation/steps
+   user_documentation/values
+   user_documentation/execution
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Dev Documentation
+
+   dev_documentation/backlog
+   dev_documentation/changelog

docs/source/user_documentation/execution.md

@@ -0,0 +1,45 @@
+# Execution
+
+Once you have written your `Scene`, the only thing left for you is to pass them to MxOps for execution.
+
+When executing `Scenes`, you will need to supply a network, a scenario and any number of `Scenes` or folders of `Scenes`.
+
+```bash
+mxops execute [-h] -s SCENARIO -n NETWORK elements [elements ...]
+```
+
+Below are some examples.
+
+## Single Scene
+
+```bash
+mxops \
+    execute \
+    -n MAIN \
+    -s compound_scenario \
+    counpound_scene.yaml
+```
+
+## Accounts Scene and Folder
+
+```bash
+mxops \
+    execute \
+    -n TEST \
+    -s integration_tests \
+    integration_tests/scenes/accounts/testnet_accounts.yaml \
+    integration_tests/scenes
+```
+
+## Accounts Scene, Folders and Files
+
+```bash
+mxops \
+    execute \
+    -n DEV \
+    -s integration_tests \
+    integration_tests/scenes/accounts/devnet_accounts.yaml \
+    integration_tests/test_1_scenes \
+    integration_tests/reset_contract_scene.yaml \
+    integration_tests/test_2_scenes \
+```

docs/source/user_documentation/getting_started.md

@@ -0,0 +1,49 @@
+# Getting Started
+
+## Installation
+
+Mxops is available on [PyPI](https://pypi.org/project/mxops/). Install it simply with pip:
+
+```bash
+pip install mxops
+```
+
+## Structure
+
+We propose a folder structure template to organise your files. This is not mandatory but should make using MxOps much easier.
+The structure is layed out as below:
+
+```bash
+.
+└── mxops_files/
+    ├── accounts/
+    │   ├── local.yaml
+    │   ├── test.yaml
+    │   ├── dev.yaml
+    │   └── main.yaml
+    ├── use_case_1/
+    │   ├── 01_first_scene.yaml
+    │   ├── 02_second_scene.yaml
+    │   └── 03_third_scene.yaml
+    ├── use_case_2/
+    │   ├── 01_first_scene.yaml
+    │   ├── 02_second_scene.yaml
+    │   ├── 03_third_scene.yaml
+    │   └── 04_fourth_scene.yaml
+    └── common_scene/
+        ├── common_scene_1.yaml
+        └── common_scene_2.yaml
+```
+
+### Accounts
+
+Accounts are grouped in separate `Scenes` to make sure you don't mix up your networks (there are other security measures in place to avoid that but we can never be to cautious).
+
+### Scene Names
+
+When you have a complexe usecase and you want to organise the `steps` in several `Scenes` to keep things clean, you should write them in a specific folder and prefix the files names with a number to make sure they will get executed in the correct order.
+
+## Next Step
+
+You are now ready to learn how to write `Scenes`!
+Heads up to the {doc}`scenes` section