Future development

[saleem-hadad]

Here are some ideas for future improvement of this library:

• Google Analytics - (#aacef69)
• Algolia Search Support - (#0271ec3)
• Authorization - (#640ca87)
• Dynamic color palette - (#55678fc)
• Dark/Light code theme - (#c577ac5)
• Organize doc files in subfolders - (#27)
• Disqus forum support - (#8b4111e)
• Medium-zoom - (#aa3dcce)
• Prism Autoloader - (#30)
• Built-in search
• Prevent docs flickering using v-clock - (#55)
• Save theme once selected by a user in local storage - (#8902a72)
• Copy to clipboard button - (#87)
• Nested Menu Alignment - (#47)
• Configureable larecipe custom components - (#108)

Confirmed coming:

• Upgrade to TailwindCSS v2
• RTL and Multi-Languages Support - (#58)
• UI editor
• Docblocks
• Language specific code tabs - (Language specific code tabs #124)
• API

Not in plan (but feel free to contribute)

• Generate static files - (#17) (e suggest to use https://jigsaw.tighten.co/ for that)
• Include files functionality - (#84)
• Passing data (Add variables to versions #138)
• Added/updated by - from git (Add variables to versions #138)

Feel free to suggest yours

[viezel]

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]

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

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]

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]

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

API Formats

• OpenAPI Spec 3.0 (JSON)
• OpenAPI/Swagger 2.0 JSON
• API Blueprint
• RAML 1.0

[johannesschobel]

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]

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

[saleem-hadad]

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]

@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]

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]

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

[ijpatricio]

hey all

@saleem-hadad

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

Docblocks FTW 👍

[johannesschobel]

@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]

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

• customizing something, publishing the views out from vendor and customize etc.
• doc blocks is just more natural to me, having it in one place

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

[ijpatricio]

@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
vuejs/vuepress#750

[johannesschobel]

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]

Update here -> #25

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

[ijpatricio]

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

[charlielangridge]

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

[kalynrobinson]

@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]

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]

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]

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]

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]

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

[rico]

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]

+1 for Subdomain

[dekts]

when the editor will available for edit the docs.

[saleem-hadad]

@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]

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]

Nice Gotcha @AbbyJanke
can you work on this?

[AbbyJanke]

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

[robsontenorio]

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]

@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]

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]

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]

How about export full pledged pdf file from docs

[anthonyaxenov]

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]

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]

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

[senter-logistics]

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

[danFWD]

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!