Improve documentation and tutorials

digicatapult / fornax

Approximate fuzzy subgraph matching in polynomial time

Apache License 2.0

21 stars 4 forks source link

Improve documentation and tutorials #4

Closed Dan-Staff closed 5 years ago

Dan-Staff commented 5 years ago

Cleaner more documented tutorial reordered to improve understanding. Additional diagrams. Better visualisation of the results. Sphinx documentation

danjust commented 5 years ago

Short intro for the README (General concept of fornax do, why, ...)
I've run into a few conflicts in the environment.yml - I can have a closer look on Monday
For me, from the README it doesn't become very clear how the target graph has to be defined
Explain the quick start results - Do you want to explain parameters like hopping distance, iterations, ...?

Dan-Staff commented 5 years ago

Short intro for the README (General concept of fornax do, why, ...)

Hi, yes. The README is a placeholder at the moment mainly for internal benefit. Can you review the tutorial linked below? You should be able to view it in the browser on GitHub without using jupyter.

https://github.com/CDECatapult/fornax/blob/documentation/notebooks/tutorial/Tutorial%202%20-%20Making%20a%20Query.ipynb?

Then I will transfer that narrative to the README file if appropriate.

I've run into a few conflicts in the environment.yml - I can have a closer look on Monday

Thanks, that's very helpful

For me, from the README it doesn't become very clear how the target graph has to be defined

See point 1 above

Explain the quick start results - Do you want to explain parameters like hopping distance, iterations, ...?

See point 1 above

Thanks for your help @danjust

danjust commented 5 years ago

Tutorial 2 looks great! Only 2 comments (apart from a general intro):

The transition to graph search before "Creating a target graph" looks a bit lost, in particular if the reader doesn't already know where this is going. I would emphasise this concept a bit more at this point.
And at least a very high level explanation of the cost/score of fornex would be interesting

danjust commented 5 years ago

Also Tutorial 2: iron_man.svg currently doesn't exist

Dan-Staff commented 5 years ago

Also Tutorial 2: iron_man.svg currently doesn't exist

Can you double check that it's there now?

Dan-Staff commented 5 years ago

I think there's now enough documentation to start working on it in a more iterate way

Dan-Staff commented 5 years ago

@mattdean-digicatapult @danjust it would be very helpful if somebody could try building the docs on their machine

also I'd really appreciate some proof reading

make sure that you tell somebody if you're going to push changed to a Jupiter notebook as they are a pain to merge.

mattdean-digicatapult commented 5 years ago

There are 388 unique characters in the dataset

Should be 399

mattdean-digicatapult commented 5 years ago

typo in tutorial:

"If we were searching a larger graph we could use a search tree as an index, an external sting matching service or database"

mattdean-digicatapult commented 5 years ago

The copyright at the bottom of each page also says Daniel Staff but should probably say something like Digital Catapult

Dan-Staff commented 5 years ago

notebook is broken, I'm trying to fix it