search

saleem-hadad / larecipe

✏️ Write and ship beautiful documentation with your Laravel applications using MarkDown
https://larecipe.saleem.dev/
MIT License
2.42k stars 265 forks source link

Future development #6

Open saleem-hadad opened 6 years ago

saleem-hadad commented 6 years ago

Here are some ideas for future improvement of this library:

Confirmed coming:

Not in plan (but feel free to contribute)

Feel free to suggest yours

viezel commented 6 years ago

Regarding generating docs from inline docblocks: http://apidocjs.com is widely used. It generates a json output which can be converted to markdown. https://github.com/softdevstory/node-apidoc-markdown of course that needs to be adjusted to meet the requirements of this project.

It would be a effective way to get adapters of Larecipe.

johannesschobel commented 6 years ago

Hey @saleem-hadad , wow, that is a cool project - i stumbled upon it by accident ;) Good work :+1:

I wanted to make the same DocBlock suggestion - because my application already uses a lot of docblocks for internal documentation.. However, i would disagree with @viezel regarding apidocJS - the project is not active any more and some kind of discontinued as stated on the github page ( https://github.com/apidoc/apidoc ). Currently there are about 200 open issues and 25 PRs that are not merged (even small readme updates, ...) and open for about 2 years+ now..

For future perspective, at least from my current point of view - i would like to try OpenAPI (aka Swagger) as this seems very promising!

However, issue with Swagger is the huge docblock overload (e.g., docblock for every model attribute, ...) which is quite uncommon for laravel itself..

What are your opinions on this?

julienbourdeau commented 6 years ago

About Search support, I'd recommend Algolia 😄, and not only because I work there haha. Algolia powers search on the Laravel docs (as well as composer, vuejs, react, yarn, packagist, and more).

You can integrate via Laravel Scout, or you can get in touch with the DocSearch team to make it easy to integrate for your users. DocSearch is entirely free, as long as the doc is for an open source projet: https://community.algolia.com/docsearch/

Very nice project, congratulations! 🎉

viezel commented 6 years ago

Sure, Apidocjs is deprecated. My main suggestion was Docblock :)

API Formats

johannesschobel commented 6 years ago

i wouldn't use the Swagger2 format, because it is already replaced by OpenApi3 (Swagger 3) and the formats are incompatible! I once worked with swagger in a PHP project and the overall handling was quite aweful.. other languages, such as c# have a very (!) good built in swagger generator.. However, at the time looking at swagger2 and swagger3, the handling was not really that good.. .

I think, API Blueprint may be a valid alternative! I found this package quite nice for a hassle-free integration with laravel: https://github.com/M165437/laravel-blueprint-docs --> UI Generation

Cool thing with API Blueprint (apiary) is the tight integration with DREDD for automated API testing..

However, it looks like that you still need to "manually" write the apib file used by the blueprint-docs-generator package above.. Haven't found a "php code annotations to apib file" package ;)

johannesschobel commented 6 years ago

oh yeah.. another point in favor for Api Blueprint: Both (laracipe & apiblueprint) use markdown!

saleem-hadad commented 6 years ago

Thank you @johannesschobel for your feedback, my pleasure 👻 Well, to be honest, I'm not a big fan of Docblock to generate docs 🤣but I'll try my best in implementing or integrating other services that @viezel mentioned once I've free time since I'm working and studying at the same time 😵 Thank you guys again for your suggestions.

saleem-hadad commented 6 years ago

@julienbourdeau haha 😂, of course, Algolia is the best 🎊I was thinking of using Laravel Scout along with Algolia for sure. I'll reach out DocSearch soon 👻 Thank you for your help and feedback.

johannesschobel commented 6 years ago

The more I think about it, the more I think that API Docs should not be part of th this package but rather be optional..

What is your opinion on this?!

saleem-hadad commented 6 years ago

Absolutely, If Docblocks implemented it gonna be as an optional plugin 👌

ijpatricio commented 6 years ago

hey all

@saleem-hadad

take a look here https://github.com/mpociot/documentarian

Docblocks FTW 👍

johannesschobel commented 6 years ago

@ijpatricio I know this package.. It has some flaws you don't want to deal with.. further, it is also quite stale..

I would highly recommend to use an established standard, like API blueprint or others..

Cheers

ijpatricio commented 6 years ago

@johannesschobel Thanks. I like the aglio.js one, but a Laravel and DocBlocks solution is a much greater fit for me. I mean

What kind of flaws? I just installed and played around a little, still to implement and use it for real...

ijpatricio commented 6 years ago

@saleem-hadad something i'm using now is vuepress, and wrap it in Laravel, serving the static asstes from a route and response with content and mimetype..

I would also gladly contribute, for snippet inclusion from file, as described here https://github.com/vuejs/vuepress/issues/750

johannesschobel commented 6 years ago

I dislike the way of the annotations.. Sure it works, I used the Laravel-doc-generator to generate the docs from code.. but didn't feel "natural" to me..

Further, I think (! Not sure !) that the format is "proprietary", i.e. It does not follow a standard.. 🤔

ijpatricio commented 6 years ago

Update here -> https://github.com/saleem-hadad/larecipe/issues/25

I think it's better to discuss on proper Issue thread, or things may become too much mixed, right??

ijpatricio commented 6 years ago

paddingTop and paddingBottom are different arguments, that default to 0 (zero).

charlielangridge commented 6 years ago

It would be great if we could 1) Change the link back to the site on the nav-bar, (eg to /home instead of the site root) 2) If it was possible to override the views, so I can theme the docs to fit with the rest of the site

baradhili commented 5 years ago

It would be nice to have the same editor you have in the blogger package, so we can create docs in laravel, instead of having to push it up.

Why? because in some cases, pushing code involves change windows/approvals etc.. editing docs would fall outside of that..

saleem-hadad commented 5 years ago

you mean providing a UI to edit them? @baradhili

saleem-hadad commented 5 years ago

I like the idea

rajmasha commented 5 years ago

It would be great if we had navigation links to different project docs in the navbar itself. When a user clicks we navigate to /project1/docs/1.0/overview and the sidebar changes as per the project selected instead of having different sub-domains for different projects.

saleem-hadad commented 5 years ago

@rajmasha you mean multi-projects documentation?

rajmasha commented 5 years ago

Yeah exactly.

kalynrobinson commented 5 years ago

@saleem-hadad can you elaborate on what you had in mind for the feature Notifications? Alternatively, is there any feature you would like me to work on?

I also wanna 👍 docblocks support. I've seen similar front-end projects that include types and parameters via a React component, like <ParamsTable for="Foo" />, which I like as a simple compromise between those who docblock and those heretics who don't.

saleem-hadad commented 5 years ago

Thank you @kalynrobinson for your awesome help. We use this package in our company and sometimes we need to notify our developers about changes in a project's specs or any requested modification, and so on. For that, I'm planning to have a small button in each page so that a developer can subscribe to get notifications if the page has been modified or new thing added.

rbcunhadesign commented 5 years ago

Is there a possibility of adding support for multiple docs?

For example, have one Laravel app with multiple documentation sets and each documentation set has its own directory/versions/search/links.

I am also using this for work (thanks for such an awesome package) but we are wanting to host all of our documentation under one auth system.

rubensrocha commented 5 years ago

Is there a possibility of adding support for multiple docs?

For example, have one Laravel app with multiple documentation sets and each documentation set has its own directory/versions/search/links.

I am also using this for work (thanks for such an awesome package) but we are wanting to host all of our documentation under one auth system.

I also agree with this feature. Join all documentations in one LaRecipe installation is a good idea.

abishekrsrikaanth commented 5 years ago

I am looking forward to having a way to edit the docs through an editor instead of updating the source and pushing them everytime.

saleem-hadad commented 5 years ago

@abishekrsrikaanth this feature will be available after supporting multi-languages

rico commented 5 years ago

I'm writing my API docs with larecipe - great software, thanks!

The main thing I'm missing is some kind of reusable data structures like in the Blueprint specification.

I try to explain. I usually work with API Resources. Naturally, from time to time I have to add or change a field in these resources. Since I can use the resource in many responses in my API (e.g. a user resource which is nested in another resource), I have to update the api docs in many places after such a change.

If I could, for instance, put my example response for a resource in a dedicated file or block, and just reference it in the docs, it would make the process a lot easier ...

jadamec commented 5 years ago

+1 for Subdomain

dekts commented 5 years ago

when the editor will available for edit the docs.

saleem-hadad commented 5 years ago

@rico Thanks for sharing this and glad you enjoy working with Larecipe Yeah, me too I'm facing the exact same issue, I use API resources a lot. in the next few days, I'll try to think in a nice solution for this issue

AbbyJanke commented 5 years ago

So right now if you have multiple themes installed, it will load the CSS Styling for all of them. Whichever one is loaded last takes precedence over the other ones. Example, using your dark theme I wanted to make some adjustments to it so created my own and only wanted to add styling for the changes i wanted but because it got loaded first (due to it going alphabetically) your dark one made my changes mute. I feel like a config for order they should be loaded would be awesome.

saleem-hadad commented 5 years ago

Nice Gotcha @AbbyJanke can you work on this?

AbbyJanke commented 5 years ago

@saleem-hadad PR #166 for the themes. Was either then I was expecting it to be in my head.

robsontenorio commented 5 years ago

UI editor would be nice, but it would require to implement some mechanism similar to a CMS, where all docs could be created from UI.

WillGoldstein commented 5 years ago

@robsontenorio like @saleem-hadad has in blogged? I kinda think it’s not totally appropriate here because there’s so much more you can do here between vue components in markdown, the alerts boxes, etc, I feel like it would be just as easy as it is now, but probably really hard to build. Though a nice Ui might keep the docs easier to understand as you’re building them - like better structure layout.

robsontenorio commented 5 years ago

Basic idea: We can deal with creating .md files on server through UI, once LaRecipe is just a Laravel/PHP application. Right? So, it would be a powerfull combo!

I would dare say it would be something similar to https://www.gitbook.com/

WillGoldstein commented 5 years ago

Ah gotchya. Yeah gitbook is absurdly expensive. Like offensively expensive. Once I found this I was very happy with my choice to go with it. Getting it closer to what gitbook offers would be sweet.

tsndp commented 5 years ago

How about export full pledged pdf file from docs

anthonyaxenov commented 5 years ago

Is there a possibility of adding support for multiple docs?

For example, have one Laravel app with multiple documentation sets and each documentation set has its own directory/versions/search/links.

I am also using this for work (thanks for such an awesome package) but we are wanting to host all of our documentation under one auth system.

Agree. It would be awesome to make something like this:

<?php // config/larecipe.php
return [
    'docs'        => [
        [
            'route'   => '/docs/admin',
            'path'    => '/resources/docs/admin',
            'landing' => 'overview',
            'middleware' => ['web', 'auth'],
        ],[
            'route'   => '/docs/user',
            'path'    => '/resources/docs/user',
            'landing' => 'overview',
            'middleware' => ['web'],
        ],
    ]
    //...
];
rfpdl commented 4 years ago

Is there a possibility of adding support for multiple docs? For example, have one Laravel app with multiple documentation sets and each documentation set has its own directory/versions/search/links. I am also using this for work (thanks for such an awesome package) but we are wanting to host all of our documentation under one auth system.

Agree. It would be awesome to make something like this:

<?php // config/larecipe.php
return [
    'docs'        => [
        [
            'route'   => '/docs/admin',
            'path'    => '/resources/docs/admin',
            'landing' => 'overview',
            'middleware' => ['web', 'auth'],
        ],[
            'route'   => '/docs/user',
            'path'    => '/resources/docs/user',
            'landing' => 'overview',
            'middleware' => ['web'],
        ],
    ]
    //...
];

This will definitely be a good feature. As we want to separate the documentation for end-users with internal users (who are managing the end users)

WillGoldstein commented 4 years ago

@saleem-hadad Heck yes. I’d pay. Keep this thing going. Love using it.

senter-logistics commented 4 years ago

i wouldn't discard this package if it was using react. It'll be great to have a react version.

danFWD commented 1 year ago

Hello, great package! Has there been any progress made on support for multiple docs? I see that this was added to the To Do list, but I don’t see any documentation for it, and when I tried to use multiple configuration arrays for the docs routing config, it threw an error. Thank you for your excellent work!