Convert Documentation to Mintlify

[jacob-macleod]

Convert the existing documentation to mintlify, which will make the docs a lot nicer to read and understand. Below are some links: https://mintlify.com/docs/quickstart#creating-your-documentation-repository https://github.com/mintlify/starter https://github.com/mintlify/starter/blob/main/mint.json

The initial setup can be based on https://github.com/mintlify/starter, but make sure you change the folder structure, possibly putting all files inside docs/ to make the repo simpler.

Setup the code to upload a static site to mintlify.

Give the documentation a blue theme, to fit in with dolphin flashcards

[kenudeh]

I'll take this up, Jacob.

[jacob-macleod]

Great, thanks!

[jacob-macleod]

Also @kenudeh I've just merged a big branch to switch databases. I've deprecated some API methods by commenting them out, which you can see in CHANGELOG.md

[jacob-macleod]

@kenudeh the new unit tests also give information on how the API routes work, and how they deal with edge cases such as when data does not exist

[kenudeh]

Hi, Jacob. I've seen the changes you made to the code base, however, they've not been reflected in the documentation. What's your opinion on how to go about that? Should I exclude /calculate-card-stats and other affected API methods from the documentation completely?

Secondly, should the unit tests be documented, too? I'll be open to doing that if you think it'll be helpful to the users.

Meanwhile, I'll be working on Mintlify seriously this week, I'll give you an update on my progress with it soon. So sorry for the long inactivity.

[jacob-macleod]

Thanks

1. If you could exclude the removed API methods from the documentation too, that would be great
2. I feel like it would take more effort than it's work to document the unit tests. You could use the unit tests to inform the main API documentation if you want (for example, use the unit tests to see what happens when you pass the API an invalid value), but that's up to you

[kenudeh]

Alright, I'll take the methods away from the documentation. Your suggestion for what to do with the unit tests is great, it's actually a good practice. I'll do exactly that and communicate the result, if I find anything odd.

[kenudeh]

Hi, @jacob-macleod. The last API docs file (goals.md) isn't showing up under the docs folder in the main branch, it only comes up under the development branch.

Can you help move it to main? Its current location makes it invincible when the repo is pulled into Mintlify.

[kenudeh]

Additionally, should I push to my main and submit a PR after making the agreed changes to statistics.md and goals.md? Or should everything be done on a different branch like the last time? Waiting for your response.

[jacob-macleod]

I've merged development into main now, so the latest code should be in main.

As to the second comment, you can do either, but please can you make a PR to development instead of main? So you can do either option so long as the code ends up from in development from your repository. That'll then mean the development and main branches are more consistent. Thanks

[kenudeh]

That's great! Thank you.

I'll follow your suggestion when sending in the PR; thanks again for the quick response.

[kenudeh]

Hello, Jacob. Can you confirm that the API supports CORS?

I'm currently writing an OpenAPI specification file for the endpoints with Stoplight (a visual editor for the OpenAPI specification). When completed, I'll use the spec file to auto-generate the definitions for the endpoints on Mintlify.

However, I can't seem to make requests to the API within Stoplight, it's suggesting that there's a CORS issue with the API, but I should point out that this was not the case with POSTMAN and regular curl requests, though. I can manoeuvre around it, just needed to draw your attention to that.

There are a few other information I need (authentication method, license information, etc.) but I'll need to get home and make a comprehensive list of them first. Lastly, please hold off on merging the pending PR, there are significant corrections to be made on some of the doc files.

[jacob-macleod]

That's strange... it should support CORS - the frontend runs on the same server as the backend, interacting through a different port. Does the error message show any more info?

Also, apologies - I forgot to merge the MR. But I'll wait until it's ready to merge

[kenudeh]

I'm not sure what the issue is; I tested another API within the project and it went through. Here's the error message:

Network Error occurred.

1. Double check that your computer is connected to the internet.
2. Make sure the API is actually running and available under the specified URL.
3. If you've checked all of the above and still experiencing issues, check if the API supports CORS.

I'm obviously connected to the internet. As for the second reason, you can look at the sample curl request generated from the editor below:

curl --request POST \
  --url http://dolphinflashcards.com/api/create-flashcard \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "userID": "user1",
  "flashcardName": "firstCard",
  "flashcardDescription": "my first flashcard",
  "folder": "folder-name/folder-2",
  "cards": [
    {
      "front": "Monday",
      "back": "Evening",
      "reviewStatus": "0.0",
      "lastReview": "01/01/2024"
    }
  ]
}'

That notwithstanding, since I'm only interested in generating a YAML file with the editor, I can keep working with it and use POSTMAN to validate API calls. I also have the alternative option of writing the spec file by hand.

[jacob-macleod]

Hmm yeah that's strange, not sure what the issue is Are you passing the json to Spotlight? Because maybe if the json is in an incorrect format, it could be raising an error, which Spotlight could be reading as a network error

[kenudeh]

Also, /delete-goal returns the string: "Goal deleted successfully" regardless of the value passed in as goalID and userID. That is, it returns that response even for non-existent goals and users.

Not sure it's a priority issue now, though. I just needed to let you know.

[kenudeh]

Hi, Jacob!

Hope you're good? I've not heard from you regarding any of the issues I raised. Meanwhile, I deleted the comments I managed to find answers to. Here are the ones still unresolved:

1. The endpoints in statistics.py are not returning expected responses. Specifically, /update-heatmap and /get-heatmap both return the error below, despite being supplied valid userIDs:

{
    "error": "User does not exist!"
}

On the other hand, /calculate-streak returns the following error:

{
    "error": "'NoneType' object is not subscriptable"
}

Can you look into them from your end?

2. Authentication: What authentication method does the API use, if any?
3. Licensing: Can you provide me with the license name and link?
4. Contact information: I need a contact URL, email, and name. Can I use contact@dolphinflashcards.com, http://dolphinflashcards.com/support, and Support as contact email, URL, and name respectively?

[jacob-macleod]

Apologies for not replying to the above message. I'll make an issue to fix it. Regarding the things you've mentioned in this message:

1. I'll investigate this. What API calls are you using to create an account?
2. At the moment there is no real authentication, but I'm planning to add some at some point
3. Dolphin uses the MIT license, from https://github.com/jacob-macleod/Dolphin-Flashcard-App/blob/main/LICENSE
4. There is no contact URL, but I'll send you the email address and name later, once I've checked what it is

[kenudeh]

Alright, thanks for the update. For the API call I used to create an account, I just made a call to /create-flashcard with a userID parameter. Could that be the problem?

[jacob-macleod]

Ah yeah - you need to use /create-account

Also, the contact email is dolphinflashcards@outlook.com and the display name is probably Dolphin Flashcards

[kenudeh]

That worked, thanks. I'll now finalize the rest of the OpenAPI file and move over to Mintlify. Everything should be ready by tomorrow at most.

[kenudeh]

Hi, Jacob!

The docs site is now live and can be found here.

Please, go through it at your convenience. I expect there'll things you may want to change/add/remove.

[jacob-macleod]

Thanks - it looks awesome! I'll look at it in more detail later. I've just noticed that the title for the introduction page is Introduction - Dolphin Flashcaards - so there's a typo

Is the code at https://github.com/kenudeh/mintlify-docs/tree/main? What would your thoughts be having the docs within the main Dolphin Flashcards repo? Would you say it would make the repo too complicated, or is it worth it for the simplicity of having a single repo?

How does the mintlify deployment work - is it possible to add multiple people to manage it? Or is it just linked to a single person (you)?

When you make a change to the code, how do you see what it looks like? Can you preview it with mintlify, or do you have to merge to main to see the rendered code in the website?

[kenudeh]

Yes, it's possible for multiple people to manage a project on Mintlify - will need to confirm if it's possible on a free plan, though.

As for the code, yes it's located at https://github.com/kenudeh/mintlify-docs/tree/main. Merging the two repos will be cumbersome, but it's not a bad idea at all. I'll be very open to that.

Meanwhile, I've seen projects where a separate repositories is maintained for documentation. There's no rule, it's just down to choices. However, I'll research on the best practices and relay my findings.

Expecting your feedback on the general docs content (both conceptual documentation and API reference).

[jacob-macleod]

@kenudeh thanks for your work on this, there are just a few things:

For /create-account, the response for the 200 response is: [ { "success": true }, 200 ]

For /create-flashcard, please can you change the last review to something that makes it obvious the date is in the dd/mm/yyyy format, such as 13/08/2024, since 13 can't be a date

A few times, you've said The card ID is The card ID, a 77-digits unique identifier of the exact flashcard retrieved from the folder. This is not quite correct, it is actually a deterministic hashed version of the card title + other data. (It is unique for each card). The same is true for flashcard ID and goal ID (and all other IDs).

Throughout the docs where relevant, but particularly for https://dolphinflashcardapp.mintlify.app/api-reference/endpoint/card-management/move-flashcard-set, please can you mention that folder locations (such as currentLocation or moveLocation) are in the format "myfolder 1/myfolder2", or if the card is in the root folder, the folder path is ""

In terms of overall things, is it possible to replace the slack thing in the menu bar with discord? If so, I'll set up a discord, and if not, I'll send you the slack link

Is the changelog copy and pasted from the main dolphin flashcards repo? If so, it'll be a pain maintaining two - what do you think the best solution would be? Maybe making the changelog link to the actual Github changelog?

[jacob-macleod]

@kenudeh in terms of repositories, I feel like it might be better to join them because then it's easier to change the docs when developers make changes. But would you like to do that now, or shall I create a new issue for it?

In terms of colors, please can you make the following changes to keep it inline with the main website (a dark mode maybe could work as well, but I feel the colors need to be tweaked to enhance readability)

primary: #6A84C5 light: #6A84C5 dark: #32519E background: light: #0D2944 dark: #0D2944 (I presume this is what is giving it the dark background?) both the anchor colors should be #6A84C5

Also, the twitter, which is linked to at the bottom of the site, is at https://x.com/dolphinflshcrds

[kenudeh]

Hi, Jacob. Thanks for the feedback! I'll now effect the corrections. For the repo, yeah, create a new issue for it. I'll attend to them all today. Sorry I couldn't respond earlier than this.

[jacob-macleod]

Hi there, have you had time to look into doing the above changes? If not, no worries. Thanks!

[kenudeh]

Hi, Jacob. Yes, I've effected majority of the changes, though I've not committed them. You talked about merging the repos? How do we go about that? Sorry, I've been a little busy lately, but I did plan on reaching out to you tomorrow.

[jacob-macleod]

No worries. In terms of merging the repos, can you tell mintlify to look in a particular folder within the repo? If so, copying all the files in the repo you made to the docs folder in dolphin flashcards, merging to development then to main, then telling mintlify to look inside the docs folder of that repository should work

Also, do you think you have enough permissions to set up Mintlify within the main dolphin flashcards repository, as opposed to the repository it is set up with at the moment? Or should I do that myself once you've added the code from your repository and merged to development, then to main?

[kenudeh]

The mint.json file is central to most things on Mintlify, but I'm not sure just copying the files into the docs folder will work. Mintlify works by cloning their starter template to new repo and installing the Mintlify GitHub app on that new repo through your Mintlify dashboard. If at all it'll work, I'll have to change the repo the docs site is currently pointing to that of the main dolphin flashcards. Not certain it'll work, but I'll give it a try.

For the permission, there's no way I'll have that. I feel ultimately have to do the following to take control of the docs site:

1. Setup a Mintlify account and link the new account to a repo (or the docs folder of the main dolphin flashcards repo, if that's possible)
2. Copy the mint.json file in addition to the api-reference, and conceptual-docs folders into the newly created repo

[kenudeh]

Typed those in a haste, so pardon the errors, if any. I'll also reach their support to see the best way to go about this. If you've already created a Mintlify account, I suggest you avoid duplicating efforts by copying the existing files from the repo I made already. I'm specifically referring to the api-reference folder, since it contains the OpenAPI YAML file that's central to the endpoints documentation. Also the mint.json file that defines the structure of the site.

[kenudeh]

Jacob, I didn't hear back from you on this. Anyway, I managed to find a slack channel with a few active Mintlify staff. I've just sent them a message, hopefully the responses will come by morning. I have space for the project this week, so everything concerning documentation should be fixed.

[jacob-macleod]

Ok, thanks, and sorry for my late reply. Let me know when you have finished all the Mintlify stuff, and I'll copy it over and look into how it would work (whether it can read from the docs folder)

[kenudeh]

Will do. Meanwhile, it appears there's something they call monorepo that can solve the problem. Will let you know.

[kenudeh]

Hello, I'm almost done with this. Ran into an unfortunate hardware issues with my PC that delayed things (it's powering on but the screen is blank). I should get it back by Monday.

[jacob-macleod]

No worries, thanks. And sorry to hear about your computer!

[jacob-macleod]

Hi there, how are you getting on with this?

[kenudeh]

Hi, Jacob. Sorry I've not updated you on things. I planned on sending you a message once I've fixed everything. My computer is ok now, it took longer than I expected for the faulty part to be delivered. Expect to hear from me within the new week! Sincere apologies for this delay. I also observed you've created an issue for the API authentication, that's cool.

[kenudeh]

Hi! Have you set up a Discord channel yet? Or would you prefer to go with Slack? Can you send me a link to any of them?

[jacob-macleod]

Ah yeah - also sorry for not replying to your earlier comment

We're using slack at the moment for development - the link is at https://join.slack.com/t/dolphinflashcards/shared_invite/zt-2pfey518m-Zw5D3xQbW94_PZAjDfLSUQ

Once you join, I'll add you to the private channel for development

Thanks

Let me know if there's any issues joining!

[kenudeh]

Got it, thank you.

On Wed, 28 Aug 2024, 10:30 Jacob MacLeod, @.***> wrote:

Ah yeah - also sorry for not replying to your earlier comment

We're using slack at the moment for development - the link is at https://join.slack.com/t/dolphinflashcards/shared_invite/zt-2pfey518m-Zw5D3xQbW94_PZAjDfLSUQ

Once you join, I'll add you to the private channel for development

Thanks

— Reply to this email directly, view it on GitHub https://github.com/jacob-macleod/Dolphin-Flashcard-App/issues/125#issuecomment-2314810073, or unsubscribe https://github.com/notifications/unsubscribe-auth/AKF7V7BWCWC3C2HTFSOOGSDZTWKBTAVCNFSM6AAAAABG6BQNJWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMJUHAYTAMBXGM . You are receiving this because you were mentioned.Message ID: @.***>

[jacob-macleod]

This is now finished