Jump to content

Provide Markdown based API documentation


gebeer
 Share

Recommended Posts

Hi all,

I would like to propose a different format for https://processwire.com/api/ref/

The PW docs should be provided as markdown.

Reasons:

  • much easier to parse for machines
  • easier to feed as context to AI assistants

Most of popular modern frameworks / libraries (laravel, whole node ecosystem, etc.) have their docs in markdown nowadays. And I think it is exactly for the reasons mentioned.

Me and also others here like @wbmnfktr are having a hard time providing meaningful context to AI assistants in IDEs like Cursor, Windsurf etc. Once those assistants have good context, they do an excellent job with PW specific code. But currently there is a lot of manual effort required to provide this context.

ProcessWire would be more accessible to a wider range of users if development could be assisted by AI in an efficient way. 

I created markdown docs with python mkdocs at https://gebeer.github.io/mkdocs-processwire/ 
WARNING: this is in it's early stages and far from complete/perfect. It is merely for demonstration purposes atm and needs a lot of polish regarding structure, index pages for each class etc.

I am using a separate local repo for scraping the API docs and parsing them to markdown.

The whole process of scraping/parsing/deploying still involves manual steps (though those could be automated). And it needs to be repeated at least for every master release of PW.

So I would prefer if @ryan could produce the API docs in markdown in the first place.

Your feedback / opinions would be much appreciated.

Cheers

 

 

  • Like 9
  • Thanks 1
Link to comment
Share on other sites

+1

Docs in markdown have been working great for me. All my module docs are markdown, so they are part of the repo (could be another repo as well, as images for example bloat the module code, which is not ideal).

I'm using RockFrontend's dom tools to enhance the markdown docs with some special features. That makes it possible to have working forms on my docs for RockForms, for example:

https://www.baumrock.com/en/processwire/modules/rockforms/docs/

## Working Example

In this example we will build the following form.

[rockforms=Quickstart]

Or another example is rendering code blocks and showing copy buttons. In markdown it's just a plain code example, on the HTML page it's an interactive element with nice labels etc:

qwtbBm6.png

## Example

This example shows how you can make every required field's label bold and add the note `optional` to every field that is not required. Note that NetteForms uses the terms `label` and `caption` for field labels.

[rockforms=Optional]

`label: /site/ready.php`
```php
$wire->addHookBefore(
  "RockForms::renderField",
  function (HookEvent $event) {
    // get the field that is rendered
    // in netteforms its called "control"
    $control = $event->arguments(1);

    // make required fields bold
    if ($control->isRequired()) {
      $control->getLabelPrototype()->addClass('uk-text-bold');
    }
    // add optional note if not required
    else {
      $renderer = $event->arguments(0);
      $label = $control->label->getText() . " <small>(optional)</small>";
      $control->setCaption($renderer->html($label));
    }
  }
);
```

 

  • Like 2
Link to comment
Share on other sites

I think this is a good idea. While the docs are not in markdown, you could use https://context7.com/?q=processwire as an MCP Server for your coding assistant (like RooCode, Cline, Windsurf, Cursor, etc) for context. Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM.

Link to comment
Share on other sites

5 hours ago, dotnetic said:

I think this is a good idea. While the docs are not in markdown, you could use https://context7.com/?q=processwire as an MCP Server for your coding assistant (like RooCode, Cline, Windsurf, Cursor, etc) for context. Context7 pulls up-to-date, version-specific documentation and code examples directly from the source. Paste accurate, relevant documentation directly into tools like Cursor, Claude, or any LLM.

Actually, Context7 was what made me start this thread. Someone has already submitted the PW repo to their scraper. But the resulting snippets are mostly garbage: https://context7.com/processwire/processwire

Now why is that?

image.png.8cf397f6b016ffbad9e51e7b328eb595.png

They do not scrape the very well documented PHP source files. If docs were in markdown, they would.

I tried the MCP and it didn't have context for simple things like WireHttp.

Does anyone know what tooling is currently used to create the PW API docs, phpDocumentor, phpDox, ApiGen or something different? 

  • Like 1
Link to comment
Share on other sites

1 hour ago, interrobang said:

I think the docs are generated with a custom module: https://processwire.com/blog/posts/processwire-3.0.41-and-a-look-at-api-explorer/

Yup. From https://processwire.com/store/pro-dev-tools/api-explorer/

Could check and see what methods are hookable to potentially generate markdown instead of HTML. Current licensing seems to indicate that using it is solely for the purpose of the license holder though, so generating Markdown from it would be usable by the developer, but not shareable. Until or unless Ryan can consider if he would also not mind generating Markdown with the official docs, it may be a more practical option for those looking to do it now.

image.png.8e9a35292ec72d9d9c40a23667604d6e.png

  • Like 1
Link to comment
Share on other sites

 Share

  • Recently Browsing   0 members

    • No registered users viewing this page.
×
×
  • Create New...