Skip to content
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.

Sign up for GitHub

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

Jump to bottom

Documentation overhaul #328

Closed
mtreinish opened this issue May 20, 2021 · 1 comment · Fixed by #339
Closed

Documentation overhaul #328

mtreinish opened this issue May 20, 2021 · 1 comment · Fixed by #339
Assignees
@IvanIsCoding
Labels
enhancement New feature or request good first issue Good for newcomers
Milestone
0.9.0

Comments

@mtreinish
Copy link
Member

What is the expected enhancement?

As we've been rapidly growing the functionality in retworkx the flat docs structure we were using before doesn't really scale. Before we push out the 0.9.0 we should work on reorganizing the documentation. The basic structure I had in mind was at the top level:

  • README
  • Graph Classes
  • Algorithms
  • Universal Functions and functions that are only applicably to single type
  • Generators and Random Graph functions
  • Visualization
    • Visualization Functions
    • Layout Functions
    • Examples (this can be in a follow up since we'd have to write all of these)
  • Detailed API Docs
    • Per graph type algorithm/functions
    • custom return types
    • exceptions

But this isn't set in stone, that's just the idea I had in my head, feel free to propose alternative structures. The key here though is to make the docs organization a bit more clear.

As part of this we also should update the graph class docstrings to include explicit mention that node and edge indices are stable unique identifiers of a node or edge for the lifetime of the graph. This isn't really explicitly called out anywhere and it's very important.
@mtreinish mtreinish added enhancement New feature or request good first issue Good for newcomers labels May 20, 2021
@mtreinish mtreinish added this to the 0.9.0 milestone May 20, 2021
@mtreinish mtreinish mentioned this issue May 20, 2021
Merged
@IvanIsCoding
Copy link
Collaborator

I will work on this. I will start by splitting the Detailed API docs (graph_*, digraph_* and methods that are less important for the user let's say) from the Algorithms section.

mtreinish added a commit to mtreinish/retworkx that referenced this issue May 27, 2021
@mtreinish
Prepare 0.9.0 release
b2770a5 
This commit starts the preparation for the 0.9.0 release. It moves all
the release notes for the release into a separate folder (to distinguish
them from notes for future releases) and also reworks the content of the
release notes and updates the documentation for the release. This commit
should be the last one merged before releasing 0.9.0 to ensure we've
moved and updated all the release notes before the release.

Partially implements Qiskit#328
@mtreinish mtreinish mentioned this issue May 27, 2021
Merged
mtreinish added a commit to mtreinish/retworkx that referenced this issue May 27, 2021
@mtreinish
Prepare 0.9.0 release
34f0476 
This commit starts the preparation for the 0.9.0 release. It moves all
the release notes for the release into a separate folder (to distinguish
them from notes for future releases) and also reworks the content of the
release notes and updates the documentation for the release. This commit
should be the last one merged before releasing 0.9.0 to ensure we've
moved and updated all the release notes before the release.

Partially implements Qiskit#328
mtreinish added a commit to mtreinish/retworkx that referenced this issue May 29, 2021
@mtreinish
Prepare 0.9.0 release
2609886 
This commit starts the preparation for the 0.9.0 release. It moves all
the release notes for the release into a separate folder (to distinguish
them from notes for future releases) and also reworks the content of the
release notes and updates the documentation for the release. This commit
should be the last one merged before releasing 0.9.0 to ensure we've
moved and updated all the release notes before the release.

Partially implements Qiskit#328
@IvanIsCoding IvanIsCoding mentioned this issue May 31, 2021
Merged
mtreinish added a commit that referenced this issue May 31, 2021
@IvanIsCoding @mtreinish
Major rework in documentation (#346)
30c1115 
This PR changes the documentation by:

* Organizing algorithms by theme instead of splitting them into universal
   and type specific
* Creating two new sections for type specific algorithms in the docs
* Functions that have no graph_* or digraph_* equivalents are listed under
  Algorithms section instead of the type Advanced API section; no function is
  listed twice

Step towards #328

* Major rework in documentation

* Address PR comments

* Remove duplicate Converters section from rebase

* Fix doc lint

Co-authored-by: Matthew Treinish <[email protected]>
mtreinish added a commit to mtreinish/retworkx that referenced this issue May 31, 2021
@mtreinish
Prepare 0.9.0 release
7d0d6aa 
This commit starts the preparation for the 0.9.0 release. It moves all
the release notes for the release into a separate folder (to distinguish
them from notes for future releases) and also reworks the content of the
release notes and updates the documentation for the release. This commit
should be the last one merged before releasing 0.9.0 to ensure we've
moved and updated all the release notes before the release.

Partially implements Qiskit#328
mtreinish added a commit that referenced this issue Jun 1, 2021
@mtreinish
Prepare 0.9.0 release (#339)
010e0de 
* Prepare 0.9.0 release

This commit starts the preparation for the 0.9.0 release. It moves all
the release notes for the release into a separate folder (to distinguish
them from notes for future releases) and also reworks the content of the
release notes and updates the documentation for the release. This commit
should be the last one merged before releasing 0.9.0 to ensure we've
moved and updated all the release notes before the release.

Partially implements #328

* Move new release notes

* Add readme section on optional dependencies

* Fix lint

* Move new release notes

* Update readme based on review comments

* Update index intro based on review comments

* Update release prelude to mention pydot_draw

* Move new release notes

* Use mpl_draw in docstrings

* Add example to graphviz_draw doc

* Update add-transitivity-function-c32d2bbbf3857c40.yaml

* Apply suggestions from code review

Co-authored-by: Ivan Carvalho <[email protected]>

* Update prepare-0.9-dab64f0197fc6233.yaml

* Update pydot-drawer-c5df0aa830679748.yaml

* Update README.md

* Update multigraph release note

* Move and update last new release note

* Add examples to spring layout release note

* Add examples to random layout

* Update add-random-layout-c1c2751be971e5d0.yaml
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@IvanIsCoding IvanIsCoding

Labels
enhancement New feature or request good first issue Good for newcomers
Projects
None yet
Milestone
0.9.0
Development

Successfully merging a pull request may close this issue.

Prepare 0.9.0 release mtreinish/retworkx
2 participants
@mtreinish @IvanIsCoding