Added contents to documentation website (#419)

AUTHORS

@@ -1,4 +1,4 @@
-Gagandeep Singh <singh.23@iitj.ac.in>
+Gagandeep Singh <gdp.1807@gmail.com>
 Kartikei Mittal <kartikeimittal@gmail.com>
 Umesh <23umesh.here@gmail.com>
 Rohan Singh <singh.77@iitj.ac.in>
@@ -7,3 +7,4 @@ Saptashrungi Birajdar <saptashrungib@gmail.com>
 Rajiv Ranjan Singh <rajivperfect007@gmail.com>
 Prashant Rawat <prashant.rawat216@gmail.com>
 Harsheet <harsheetkakar@gmail.com>
+Pratik Goyal <pratikgoyal2712@gmail.com>

docs/source/authors.rst

@@ -0,0 +1,27 @@
+Authors
+=======
+
+The following contributors wanted themselves to be added as
+authors of the project. If you too have contributed to PyDataStructs
+and want to be considered as author then feel free to open a PR editing
+``docs/source/authors.rst`` and ``AUTHORS`` files.
+
+Gagandeep Singh <gdp.1807@gmail.com>
+
+Kartikei Mittal <kartikeimittal@gmail.com>
+
+Umesh <23umesh.here@gmail.com>
+
+Rohan Singh <singh.77@iitj.ac.in>
+
+Tarun Singh Tomar <tomartarun2001@gmail.com>
+
+Saptashrungi Birajdar <saptashrungib@gmail.com>
+
+Rajiv Ranjan Singh <rajivperfect007@gmail.com>
+
+Prashant Rawat <prashant.rawat216@gmail.com>
+
+Harsheet <harsheetkakar@gmail.com>
+
+Pratik Goyal <pratikgoyal2712@gmail.com>

docs/source/contributing.rst

@@ -0,0 +1,74 @@
+How to contribute?
+==================
+
+Follow the steps given below,
+
+1. Fork, https://github.com/codezonediitj/pydatastructs/
+2. Execute, ``git clone https://github.com/codezonediitj/pydatastructs/``
+3. Change your working directory to ``../pydatastructs``.
+4. Execute, ``git remote add origin_user https://github.com/<your-github-username>/pydatastructs/``
+5. Execute, ``git checkout -b <your-new-branch-for-working>``.
+6. Make changes to the code.
+7. Add your name and email to the ``AUTHORS``, if you wish to.
+8. Execute, ``git add .``.
+9. Execute, ``git commit -m "your-commit-message"``.
+10. Execute, ``git push origin_user <your-current-branch>``.
+11. Make PR.
+
+That's it, 10 easy steps for your first contribution. For 
+future contributions just follow steps 5 to 10. Make sure that 
+before starting work, always checkout to ``master`` and pull the 
+recent changes using the remote ``origin`` and then start from steps 
+5 to 10.
+
+See you soon with your first PR.
+
+It is recommended to go through the following links before you start working.
+
+- `Issue Policy <https://github.com/codezonediitj/pydatastructs/wiki/Issue-Policy>`_
+- `Pull Request Policy <https://github.com/codezonediitj/pydatastructs/wiki/Pull-Request-Policy>`_
+- `Plan of Action for the Projects <https://github.com/codezonediitj/pydatastructs/wiki/Plan-of-Action-for-the-Projects>`_
+
+Testing
+-------
+
+For testing your patch locally follow the steps given below,
+
+1. Install `pytest-cov <https://pypi.org/project/pytest-cov/>`_. Skip this step if you are already having the package.
+2. Run, ``python3 -m pytest --doctest-modules --cov=./ --cov-report=html``. Look for, ``htmlcov/index.html`` and open it 
+in your browser, which will show the coverage report. Try to ensure that the coverage is not decreasing by more than 1% 
+for your patch.
+
+For a good visualisation of the different data structures and algorithms, refer the following websites:
+
+- https://visualgo.net/
+
+- https://www.cs.usfca.edu/~galles/visualization/
+
+You can use the examples given in the following book as tests for your code:
+
+- `https://opendatastructures.org/ods-python.pdf <https://opendatastructures.org/ods-python.pdf>`_
+
+
+Guidelines
+----------
+
+We recommend you to join our `gitter channel <https://gitter.im/codezoned2017/Lobby>`_ for discussing anything related to the project.
+
+Please follow the rules and guidelines given below,
+
+1. Follow the `numpydoc docstring guide <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
+2. If you are planning to contribute a new data structure then first raise an **issue** for discussing the API, rather than directly making a PR. Please go through `Plan of Action for Adding New Data Structures <https://github.com/codezonediitj/pydatastructs/wiki/Plan-of-Action-for-Adding-New-Data-Structures>`_.
+3. For the first-time contributors we recommend not to take a complex data structure, rather start with ``beginner`` or ``easy``.
+4. We don't assign issues to any individual. Instead, we follow First Come First Serve for taking over issues, i.e., if one contributor has already shown interest then no comment should be made after that as it won't be considered. Anyone willing to work on an issue can comment on the thread that he/she is working on and raise a PR for the same.
+5. Any open PR must be provided with some updates after being reviewed. If it is stalled for more than 4 days, it will be labeled as ``Please take over``, meaning that anyone willing to continue that PR can start working on it.
+6. PRs that are not related to the project or don't follow any guidelines will be labeled as ``Could Close``, meaning that the PR is not necessary at the moment.
+
+The following parameters are to be followed to pass the code quality tests for your Pull Requests,
+
+1. There should not be any trailing white spaces at any line of code.
+2. Each ``.py`` file should end with exactly one new line.
+3. Comparisons involving ``True``, ``False`` and ``None`` should be done by
+reference (using ``is``, ``is not``) and not by value(``==``, ``!=``).
+
+Keep contributing!!

docs/source/index.rst

@@ -20,10 +20,45 @@ code in C++ and Java as well.
 
    This project is under active development and contributions are welcome.
 
+Installation
+============
+
+After changing your directory to project root, you can 
+install the package by running the following command,
+
+``python -m pip install .``
+
+For development purposes, you can use the option `e` as shown below,
+
+``python -m pip install -e .``
+
+For building documentation execute the following commands one after
+the other,
+
+1. ``pip install -r docs/requirements.txt``
+2. ``sphinx-build -b html docs/source/ docs/build/html``
+
+Make sure that your python version is at least ``3.8``.
+
+Why do we use Python?
+=====================
+
+As we know Python is an interpreted language and hence is 
+slow compared to C++, the most popular language for competitive programming. 
+We still decided to use Python because the software development can happen 
+at a much faster pace and it is much easier to test various software designs 
+and APIs as coding them out takes no time. However, keeping the need of the 
+users in mind, we will shift to C++ backend,  which will happen quickly as 
+we would be required to just translate the tested code rather than writing it 
+from scratch, after a few releases with APIs available for all the languages.
+
 Contents
 ========
 
 .. toctree::
    :maxdepth: 1
 
+   tutorials.rst
+   contributing.rst
+   authors.rst
    pydatastructs/pydatastructs.rst

docs/source/tutorials.rst

@@ -0,0 +1,119 @@
+Tutorials
+=========
+
+We provide the following tutorials to show how ``pydatastructs`` 
+APIs can help in solving complicated data structures and algorithms 
+problems easily. For now the problems are abstract. However, we plan 
+to add some examples showing usage of ``pydatastructs`` on real world 
+data sets such as `Stanford Large Network Dataset Collection <https://snap.stanford.edu/data/>`_
+and `Urban Dictionary Words And Definitions <https://www.kaggle.com/therohk/urban-dictionary-words-dataset>`_.
+If you are interested in playing around with the above datasets using our API,
+then please feel free to reach out to us on our community channels.
+
+Max-Min Stream
+--------------
+
+In this problem, we will be dealing with a stream of integer numbers. We have to 
+display the ``k``-th largest and ``k``-th smallest number for all the prefixes of the 
+input stream. In simple words, after reading each number, we have to display 
+the ``k``-th largest and ``k``-th smallest number up until that number in the stream. 
+If the size of the stream is smaller than ``k`` then we will display the minimum 
+for ``k``-th smallest and maximum for ``k``-th largest numbers respectively.
+
+**Input Format**
+
+The first line of input will contain the value, ``k``. After that, each line of 
+input will contain an integer representing the new number of the stream. The stopping 
+point of the stream will be denoted by 0. Note that stopping point i.e., 0 will also 
+be considered a part of the input stream.
+
+**Output Format**
+
+Each line of the output should contain two space separated numbers, the first one 
+representing the ``k``-th largest/maximum number and the second one representing 
+the ``k``-th smallest/minimum number.
+
+>>> from pydatastructs import BinaryHeap, Queue
+>>> def modify_heaps(min_heap, max_heap, curr_num, k):
+...     min_heap.insert(curr_num)
+...     max_heap.insert(curr_num)
+...     if min_heap.heap._num > k:
+...         min_heap.extract()
+...     if max_heap.heap._num > k:
+...         max_heap.extract()
+...     large, small = (max_heap.heap[0].key, min_heap.heap[0].key)
+...     return large, small
+... 
+>>> min_heap = BinaryHeap(heap_property='min')
+>>> max_heap = BinaryHeap(heap_property='max')
+>>> k = 2
+>>> curr_nums = Queue(items=[4, 5, 8, 0]) # input stream as a list
+>>> curr_num = curr_nums.popleft()
+>>> large_small = []
+>>> while curr_num != 0:
+...     large, small = modify_heaps(min_heap, max_heap, curr_num, k)
+...     large_small.append((large, small))
+...     curr_num = curr_nums.popleft()
+... 
+>>> large, small = modify_heaps(min_heap, max_heap, curr_num, k)
+>>> large_small.append((large, small))
+>>> print(large_small)
+[(4, 4), (5, 4), (5, 5), (4, 5)]
+
+Minimise Network Delay
+----------------------
+
+In this problem there will be a network containing ``N`` nodes, labelled as 1 ... ``N``, and ``E`` edges. 
+Any two nodes may be connected by an undirected edge ``E(u, v)`` and introduces a delay of time ``t(u, v)`` 
+in transfer of information between the nodes ``u`` and ``v``.
+
+We will be given ``K`` queries where each query contains the source node and the destination node and 
+we will be required to determine the minimum time it will take for a piece of information to start from 
+the source node and reach at the destination node.
+
+We will assume that the size of information and the processing time at any node doesn’t affect the  travel time.
+
+**Input Format**
+
+The first line will contain a single positive integer ``N``.
+
+The second line will contain a single positive integer ``E``.
+
+Then ``E`` lines will follow, each line containing three space separated integers. 
+The first two denoting node labels connected by an undirected edge which introduces 
+a time delay denoted by the third integer.
+
+After that the next line will contain a positive integer ``K``.
+
+Then ``K`` lines will follow each containing two space separated node labels, the 
+first denoting the source node and the second one denoting the destination node for that query.
+
+**Output Format**
+
+``K`` lines, each containing the minimum time required for the ``k``-th query.
+
+>>> from pydatastructs import Graph, AdjacencyListGraphNode
+>>> from pydatastructs.graphs.algorithms import shortest_paths
+>>> N = 4
+>>> E = 3
+>>> nodes = []
+>>> for n in range(N):
+...     nodes.append(AdjacencyListGraphNode(str(n + 1)))
+... 
+>>> u_v_t = [(1, 2, 1), (2, 3, 1), (3, 4, 1)] # edges and their time delay
+>>> graph = Graph(*nodes)
+>>> for e in range(E):
+...     u, v, t = u_v_t[e]
+...     graph.add_edge(str(u), str(v), t)
+...     graph.add_edge(str(v), str(u), t)
+... 
+>>> K = 3
+>>> u_v = [(1, 4), (3, 2), (4, 3)] # queries
+>>> delays = []
+>>> for k in range(K):
+...     u, v = u_v[k]
+...     delay = shortest_paths(graph, 'dijkstra', str(u))[0]
+...     delays.append(delay[str(v)])
+... 
+>>> print(delays)
+[3, 1, 1]