Skip to content

Added contents to documentation website #419

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 24, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AUTHORS
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
Gagandeep Singh <[email protected]>
Gagandeep Singh <[email protected]>
Kartikei Mittal <[email protected]>
Umesh <[email protected]>
Rohan Singh <[email protected]>
Expand All @@ -7,3 +7,4 @@ Saptashrungi Birajdar <[email protected]>
Rajiv Ranjan Singh <[email protected]>
Prashant Rawat <[email protected]>
Harsheet <[email protected]>
Pratik Goyal <[email protected]>
27 changes: 27 additions & 0 deletions docs/source/authors.rst
Original file line number Diff line number Diff line change
@@ -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 <[email protected]>

Kartikei Mittal <[email protected]>

Umesh <[email protected]>

Rohan Singh <[email protected]>

Tarun Singh Tomar <[email protected]>

Saptashrungi Birajdar <[email protected]>

Rajiv Ranjan Singh <[email protected]>

Prashant Rawat <[email protected]>

Harsheet <[email protected]>

Pratik Goyal <[email protected]>
74 changes: 74 additions & 0 deletions docs/source/contributing.rst
Original file line number Diff line number Diff line change
@@ -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!!
35 changes: 35 additions & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
119 changes: 119 additions & 0 deletions docs/source/tutorials.rst
Original file line number Diff line number Diff line change
@@ -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]