Reorganize code into modules

[IvanIsCoding]

Closes #300

The organization steps were:

• Group code by topics in api.rst
• For small topics, use topic.rs
• For larger topics, create topic/mod.rs for the Python implementations and topic/xyz.rs for implementations

Details worth sharing are:

• weight_callable and NodeRemoved stayed at lib.rs because they are omnipresent; because they are pure Rust code I thought it was a reasonable place
• wrap_pyfunction(module_name::function_name) is currently not supported, so all functions had to be imported
• Some modules from the "Others" section in the docs are small; they could be groupped together but other_algo did not feel very descriptive

[coveralls]

Pull Request Test Coverage Report for Build 1105247807

• 2918 of 2989 (97.62%) changed or added relevant lines in 26 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage decreased (-0.04%) to 96.21%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
src/layout/shell.rs	44	45	97.78%
src/matching/mod.rs	80	81	98.77%
src/shortest_path/all_pairs_dijkstra.rs	162	163	99.39%
src/traversal/mod.rs	68	69	98.55%
src/tree.rs	46	48	95.83%
src/union.rs	10	12	83.33%
src/layout/bipartite.rs	63	66	95.45%
src/isomorphism/mod.rs	134	138	97.1%
src/random_graph.rs	281	287	97.91%
src/dag_algo/mod.rs	340	348	97.7%

Totals
Change from base Build 1098516602:	-0.04%
Covered Lines:	8783
Relevant Lines:	9129

---

💛 - Coveralls

[georgios-ts]

Wow, I love this!
Some comments:

• random_circuit -> random_graphs? I'd also be happy if we merge random graph functions and generators.rs.
• Move simple_path.rs code (or even core_number.rs, *_adjacency_matrix) into connectivity.rs.
• topological_sort, lexicographical_topological_sort and collect_runs are inside traversal folder. I'd move them into dag_algo.
• Not a fan of the folder naming: *_algo. Can we remove it, i.e layout_algo -> layout?

[IvanIsCoding]

Wow, I love this!
Some comments:

• random_circuit -> random_graphs? I'd also be happy if we merge random graph functions and generators.rs.
• Move simple_path.rs code (or even core_number.rs, *_adjacency_matrix) into connectivity.rs.
• topological_sort, lexicographical_topological_sort and collect_runs are inside traversal folder. I'd move them into dag_algo.
• Not a fan of the folder naming: *_algo. Can we remove it, i.e layout_algo -> layout?

I agree layout_algo is not the best name. I wanted to name it layout but clippy complalins about module inception i.e. mod layout inside layout. I think I will just disable the warning and go ahead.

Edit:

• random_circuit has been renamed random_graph
• Incorporated more items into the connectivity module
• Moved the items from traversal to dag_algo
• The only *_algo left is dag_algo, which seems reasonable given they are listed under DAG Algorithms

I didn't merge random_graph with generators because generators exports items under retworkx.generators, and random_graph needs to export items under retworkx

[mtreinish]

Overall this is awesome! I'm really happy to get rid of the 5k line (and continuing to grow) lib.rs and put things in real modules. I'd like to move forward on merging this sooner rather than later since it basically conflicts with every other PR. Now that we have a more organized structure we can continue to bikeshed on where things go moving forward, especially as it doesn't actually effect our user API we have the freedom to move things around a lot. I just had 2 inline comments on alternatives to avoid the module inception.

Also, it would be really good if you could add something to:
https://github.com/Qiskit/retworkx/blob/main/CONTRIBUTING.md about the code structure now. Basically about how lib.rs is for the python module exports and global code, where we put pyfunction definitions vs pure rust code, standalone modules vs directories, etc. Once the contributing guide is updated I think this is ready to go.

[IvanIsCoding]

Overall this is awesome! I'm really happy to get rid of the 5k line (and continuing to grow) lib.rs and put things in real modules. I'd like to move forward on merging this sooner rather than later since it basically conflicts with every other PR. Now that we have a more organized structure we can continue to bikeshed on where things go moving forward, especially as it doesn't actually effect our user API we have the freedom to move things around a lot. I just had 2 inline comments on alternatives to avoid the module inception.

Also, it would be really good if you could add something to:
https://github.com/Qiskit/retworkx/blob/main/CONTRIBUTING.md about the code structure now. Basically about how lib.rs is for the python module exports and global code, where we put pyfunction definitions vs pure rust code, standalone modules vs directories, etc. Once the contributing guide is updated I think this is ready to go.

I incorporated the feedback, now we no longer have module inceptions.

I also added a small section on CONTRIBUTING.md, it is a start on explaining the structure and which file contributors will need to change

[mtreinish]

Overall this is great. Thanks for making those updates quickly. I've got a few inline nits on the contributor docs but nothing major, I'll just apply them and merge this! Then we have the fun of rebasing everything :)

[mtreinish]

I was just curious if there was an impact on compile time, I just did side by side testing locally and there was no difference for me with this PR applied.