Skip to content

Commit 3bd7e5a

Browse files
czgdp1807czgdp1807
authored
Added contents to documentation website (#419)
1 parent 2a7d6c7 commit 3bd7e5a

File tree

5 files changed

+257
-1
lines changed

5 files changed

+257
-1
lines changed

‎AUTHORS

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Gagandeep Singh <singh.23@iitj.ac.in>
1+
Gagandeep Singh <gdp.1807@gmail.com>
22
Kartikei Mittal <kartikeimittal@gmail.com>
33
Umesh <23umesh.here@gmail.com>
44
Rohan Singh <singh.77@iitj.ac.in>
@@ -7,3 +7,4 @@ Saptashrungi Birajdar <saptashrungib@gmail.com>
77
Rajiv Ranjan Singh <rajivperfect007@gmail.com>
88
Prashant Rawat <prashant.rawat216@gmail.com>
99
Harsheet <harsheetkakar@gmail.com>
10+
Pratik Goyal <pratikgoyal2712@gmail.com>

‎docs/source/authors.rst

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Authors
2+
=======
3+
4+
The following contributors wanted themselves to be added as
5+
authors of the project. If you too have contributed to PyDataStructs
6+
and want to be considered as author then feel free to open a PR editing
7+
``docs/source/authors.rst`` and ``AUTHORS`` files.
8+
9+
Gagandeep Singh <gdp.1807@gmail.com>
10+
11+
Kartikei Mittal <kartikeimittal@gmail.com>
12+
13+
Umesh <23umesh.here@gmail.com>
14+
15+
Rohan Singh <singh.77@iitj.ac.in>
16+
17+
Tarun Singh Tomar <tomartarun2001@gmail.com>
18+
19+
Saptashrungi Birajdar <saptashrungib@gmail.com>
20+
21+
Rajiv Ranjan Singh <rajivperfect007@gmail.com>
22+
23+
Prashant Rawat <prashant.rawat216@gmail.com>
24+
25+
Harsheet <harsheetkakar@gmail.com>
26+
27+
Pratik Goyal <pratikgoyal2712@gmail.com>

‎docs/source/contributing.rst

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
How to contribute?
2+
==================
3+
4+
Follow the steps given below,
5+
6+
1. Fork, https://github.com/codezonediitj/pydatastructs/
7+
2. Execute, ``git clone https://github.com/codezonediitj/pydatastructs/``
8+
3. Change your working directory to ``../pydatastructs``.
9+
4. Execute, ``git remote add origin_user https://github.com/<your-github-username>/pydatastructs/``
10+
5. Execute, ``git checkout -b <your-new-branch-for-working>``.
11+
6. Make changes to the code.
12+
7. Add your name and email to the ``AUTHORS``, if you wish to.
13+
8. Execute, ``git add .``.
14+
9. Execute, ``git commit -m "your-commit-message"``.
15+
10. Execute, ``git push origin_user <your-current-branch>``.
16+
11. Make PR.
17+
18+
That's it, 10 easy steps for your first contribution. For
19+
future contributions just follow steps 5 to 10. Make sure that
20+
before starting work, always checkout to ``master`` and pull the
21+
recent changes using the remote ``origin`` and then start from steps
22+
5 to 10.
23+
24+
See you soon with your first PR.
25+
26+
It is recommended to go through the following links before you start working.
27+
28+
- `Issue Policy <https://github.com/codezonediitj/pydatastructs/wiki/Issue-Policy>`_
29+
- `Pull Request Policy <https://github.com/codezonediitj/pydatastructs/wiki/Pull-Request-Policy>`_
30+
- `Plan of Action for the Projects <https://github.com/codezonediitj/pydatastructs/wiki/Plan-of-Action-for-the-Projects>`_
31+
32+
Testing
33+
-------
34+
35+
For testing your patch locally follow the steps given below,
36+
37+
1. Install `pytest-cov <https://pypi.org/project/pytest-cov/>`_. Skip this step if you are already having the package.
38+
2. Run, ``python3 -m pytest --doctest-modules --cov=./ --cov-report=html``. Look for, ``htmlcov/index.html`` and open it
39+
in your browser, which will show the coverage report. Try to ensure that the coverage is not decreasing by more than 1%
40+
for your patch.
41+
42+
For a good visualisation of the different data structures and algorithms, refer the following websites:
43+
44+
- https://visualgo.net/
45+
46+
- https://www.cs.usfca.edu/~galles/visualization/
47+
48+
You can use the examples given in the following book as tests for your code:
49+
50+
- `https://opendatastructures.org/ods-python.pdf <https://opendatastructures.org/ods-python.pdf>`_
51+
52+
53+
Guidelines
54+
----------
55+
56+
We recommend you to join our `gitter channel <https://gitter.im/codezoned2017/Lobby>`_ for discussing anything related to the project.
57+
58+
Please follow the rules and guidelines given below,
59+
60+
1. Follow the `numpydoc docstring guide <https://numpydoc.readthedocs.io/en/latest/format.html>`_.
61+
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>`_.
62+
3. For the first-time contributors we recommend not to take a complex data structure, rather start with ``beginner`` or ``easy``.
63+
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.
64+
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.
65+
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.
66+
67+
The following parameters are to be followed to pass the code quality tests for your Pull Requests,
68+
69+
1. There should not be any trailing white spaces at any line of code.
70+
2. Each ``.py`` file should end with exactly one new line.
71+
3. Comparisons involving ``True``, ``False`` and ``None`` should be done by
72+
reference (using ``is``, ``is not``) and not by value(``==``, ``!=``).
73+
74+
Keep contributing!!

‎docs/source/index.rst

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,45 @@ code in C++ and Java as well.
2020

2121
This project is under active development and contributions are welcome.
2222

23+
Installation
24+
============
25+
26+
After changing your directory to project root, you can
27+
install the package by running the following command,
28+
29+
``python -m pip install .``
30+
31+
For development purposes, you can use the option `e` as shown below,
32+
33+
``python -m pip install -e .``
34+
35+
For building documentation execute the following commands one after
36+
the other,
37+
38+
1. ``pip install -r docs/requirements.txt``
39+
2. ``sphinx-build -b html docs/source/ docs/build/html``
40+
41+
Make sure that your python version is at least ``3.8``.
42+
43+
Why do we use Python?
44+
=====================
45+
46+
As we know Python is an interpreted language and hence is
47+
slow compared to C++, the most popular language for competitive programming.
48+
We still decided to use Python because the software development can happen
49+
at a much faster pace and it is much easier to test various software designs
50+
and APIs as coding them out takes no time. However, keeping the need of the
51+
users in mind, we will shift to C++ backend, which will happen quickly as
52+
we would be required to just translate the tested code rather than writing it
53+
from scratch, after a few releases with APIs available for all the languages.
54+
2355
Contents
2456
========
2557

2658
.. toctree::
2759
:maxdepth: 1
2860

61+
tutorials.rst
62+
contributing.rst
63+
authors.rst
2964
pydatastructs/pydatastructs.rst

‎docs/source/tutorials.rst

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
Tutorials
2+
=========
3+
4+
We provide the following tutorials to show how ``pydatastructs``
5+
APIs can help in solving complicated data structures and algorithms
6+
problems easily. For now the problems are abstract. However, we plan
7+
to add some examples showing usage of ``pydatastructs`` on real world
8+
data sets such as `Stanford Large Network Dataset Collection <https://snap.stanford.edu/data/>`_
9+
and `Urban Dictionary Words And Definitions <https://www.kaggle.com/therohk/urban-dictionary-words-dataset>`_.
10+
If you are interested in playing around with the above datasets using our API,
11+
then please feel free to reach out to us on our community channels.
12+
13+
Max-Min Stream
14+
--------------
15+
16+
In this problem, we will be dealing with a stream of integer numbers. We have to
17+
display the ``k``-th largest and ``k``-th smallest number for all the prefixes of the
18+
input stream. In simple words, after reading each number, we have to display
19+
the ``k``-th largest and ``k``-th smallest number up until that number in the stream.
20+
If the size of the stream is smaller than ``k`` then we will display the minimum
21+
for ``k``-th smallest and maximum for ``k``-th largest numbers respectively.
22+
23+
**Input Format**
24+
25+
The first line of input will contain the value, ``k``. After that, each line of
26+
input will contain an integer representing the new number of the stream. The stopping
27+
point of the stream will be denoted by 0. Note that stopping point i.e., 0 will also
28+
be considered a part of the input stream.
29+
30+
**Output Format**
31+
32+
Each line of the output should contain two space separated numbers, the first one
33+
representing the ``k``-th largest/maximum number and the second one representing
34+
the ``k``-th smallest/minimum number.
35+
36+
>>> from pydatastructs import BinaryHeap, Queue
37+
>>> def modify_heaps(min_heap, max_heap, curr_num, k):
38+
... min_heap.insert(curr_num)
39+
... max_heap.insert(curr_num)
40+
... if min_heap.heap._num > k:
41+
... min_heap.extract()
42+
... if max_heap.heap._num > k:
43+
... max_heap.extract()
44+
... large, small = (max_heap.heap[0].key, min_heap.heap[0].key)
45+
... return large, small
46+
...
47+
>>> min_heap = BinaryHeap(heap_property='min')
48+
>>> max_heap = BinaryHeap(heap_property='max')
49+
>>> k = 2
50+
>>> curr_nums = Queue(items=[4, 5, 8, 0]) # input stream as a list
51+
>>> curr_num = curr_nums.popleft()
52+
>>> large_small = []
53+
>>> while curr_num != 0:
54+
... large, small = modify_heaps(min_heap, max_heap, curr_num, k)
55+
... large_small.append((large, small))
56+
... curr_num = curr_nums.popleft()
57+
...
58+
>>> large, small = modify_heaps(min_heap, max_heap, curr_num, k)
59+
>>> large_small.append((large, small))
60+
>>> print(large_small)
61+
[(4, 4), (5, 4), (5, 5), (4, 5)]
62+
63+
Minimise Network Delay
64+
----------------------
65+
66+
In this problem there will be a network containing ``N`` nodes, labelled as 1 ... ``N``, and ``E`` edges.
67+
Any two nodes may be connected by an undirected edge ``E(u, v)`` and introduces a delay of time ``t(u, v)``
68+
in transfer of information between the nodes ``u`` and ``v``.
69+
70+
We will be given ``K`` queries where each query contains the source node and the destination node and
71+
we will be required to determine the minimum time it will take for a piece of information to start from
72+
the source node and reach at the destination node.
73+
74+
We will assume that the size of information and the processing time at any node doesn’t affect the travel time.
75+
76+
**Input Format**
77+
78+
The first line will contain a single positive integer ``N``.
79+
80+
The second line will contain a single positive integer ``E``.
81+
82+
Then ``E`` lines will follow, each line containing three space separated integers.
83+
The first two denoting node labels connected by an undirected edge which introduces
84+
a time delay denoted by the third integer.
85+
86+
After that the next line will contain a positive integer ``K``.
87+
88+
Then ``K`` lines will follow each containing two space separated node labels, the
89+
first denoting the source node and the second one denoting the destination node for that query.
90+
91+
**Output Format**
92+
93+
``K`` lines, each containing the minimum time required for the ``k``-th query.
94+
95+
>>> from pydatastructs import Graph, AdjacencyListGraphNode
96+
>>> from pydatastructs.graphs.algorithms import shortest_paths
97+
>>> N = 4
98+
>>> E = 3
99+
>>> nodes = []
100+
>>> for n in range(N):
101+
... nodes.append(AdjacencyListGraphNode(str(n + 1)))
102+
...
103+
>>> u_v_t = [(1, 2, 1), (2, 3, 1), (3, 4, 1)] # edges and their time delay
104+
>>> graph = Graph(*nodes)
105+
>>> for e in range(E):
106+
... u, v, t = u_v_t[e]
107+
... graph.add_edge(str(u), str(v), t)
108+
... graph.add_edge(str(v), str(u), t)
109+
...
110+
>>> K = 3
111+
>>> u_v = [(1, 4), (3, 2), (4, 3)] # queries
112+
>>> delays = []
113+
>>> for k in range(K):
114+
... u, v = u_v[k]
115+
... delay = shortest_paths(graph, 'dijkstra', str(u))[0]
116+
... delays.append(delay[str(v)])
117+
...
118+
>>> print(delays)
119+
[3, 1, 1]

0 commit comments

Comments
 (0)