Sounds like we should have a list of our own helpers, with limited guidance about Zend's helpers. We can't document all of Zend's stuff, but a handful of examples from Zend will help clarify the difference (and why we're not documenting all of theirs)

The documentation for the API lists out resources available, but it looks like the resources Resource isn't publicly accessible.

There might be a difference here and there between the internal and external API behavior?

Tutorial.

• Introduction: renderers and ingesters are about expanding the kinds of things users can describe and present/exhibit/etc.
• discussion of renderers/ingesters being able to work both with uploaded files and with remote content
• necessary elements of adding one: configuration keys, classes, methods

This should be tutorial-type content:

• briefly what blocks do, that they're the way to extend what users can add to pages
• the necessary structure in terms of the class, what to do with the methods
• conventions like using partials for form/output rendering

currently, it reads like the logger it automatically there. it isn't. it needs to be retrieved from the service locator

First draft, so much will change, but figuring out a sense of priorities, and whether the basic sections here need immediate adjustment should happen quickly. Any thoughts from @zerocrates @jimsafley @kalbers @kimisgold appreciated

If you are out of date, the suggested path to how to do updates ignores that multiple modules, and indeed core, could give SQL update instruction when running the update sql tool.

We'll need to give guidance about parsing that out for what a developer needs to pay attention to.

Zend's spelling and the spelling used in the config files is "invokable" so we need to be using that spelling.

The paths in this documentation are all over the place - we have /default/collections/browse.phtml and /default/views/omeka/site/collection

In the introduction, we have a singular 'view' for the theme:

view: Files within this directory are the meat of a theme. These customized theme files override Omeka S default view template files located in application/views/.

might be worth cleaning up.

Part of #8

• the advice about getView is tricky as that's really specific to where you are
  many/most places don't have a getView method to call
  some places we pass $view in to the appropriate method or whatever to let you call stuff

• i hesitate about the description of the use case for factories being "additional data"
  it's other services that usually causes you to need a factory

• i assume you need "common" in that view helper using partial example, when you're actually calling the partial

• the user role bit of the example might be more confusing than helpful, i dunno

• i think the major bit you don't cover is that you can take arguments in __invoke
  that's the preferred and easiest way of getting in data, just make the theme writer pass it to you

I'm a fair amount through enough of the writing that it's worth asking at this point if/where I'm going astray in any aspects of the dev documentation. If you don't want to read markdown, the README has minimal info on how to build HTML to read it (how to incorporate a build into the real site is still up for grabs).

There are still lots of blank pages, but ones that have content under Key Concepts are:

• Access Control Lists
• Debugging
• Doctrine and Entities
• Forms
• Internal Api
• Internationalization
• Modules
• Omeka Events

These reflect a bunch of move-overs from the existing wiki, some of which contains updates for the current state of affairs.

Much more for me to work on, but no reason not to ask if people want to look now.

Any thoughts, @jimsafley @zerocrates @kalbers @kimisgold ?

Thanks

We have some of this in the API page but we should have a page that has every possible parameter.

Github now allows you to use actions that could create a release and attach a zipped version of the module for you. Putting an example action in the documentation (docs/register_an_addon.md) might be very helpful. Here is the one I use for the Any Cloud module. You create a tag with the version of the module you want to create a release for (v2.2.3 for example) and the action takes over from there:

.github/workflows/release.yml

name: Release
on:
  push:
    tags:
      - '*'
jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: "Checkout repository"
        uses: "actions/checkout@master"
      - name: "Set up PHP"
        uses: "shivammathur/setup-php@v2"
        with:
          php-version: "latest"
      - name: "Composer install"
        uses: "ramsey/composer-install@v2"
        with:
          composer-options: "--ignore-platform-reqs --optimize-autoloader"
      - name: "Create archive release"
        uses: "thedoctor0/zip-release@master"
        with:
          filename: "{AddonZipName}.zip"
          exclusions: "*.git* .tx/ language/*.po* .editorconfig phpcs.xml.dist"
      - name: Upload Release
        uses: ncipollo/release-action@v1
        with:
          artifacts: '{AddonZipName}.zip'
          bodyFile: "RELEASE.md"
          token: ${{ secrets.GITHUB_TOKEN }}

It downloads composer, installs the versions of the dependencies indicated in your composer.lock file in the repository, zips everything up except what you put in the exclusions section, and adds the text of RELEASE.md as the text of the release.

In any case, this might be helpful to other developers and make things a little easier than manually uploaded a .zip file to every release. Creating a git tag for a release and letting GitHub do all the other work is really helpful.

Generated documentation seems to be having diminishing returns since last investigated.

ApiGen is looking for a new maintainer. It's been painful and unsuccessful to revert back to the version that generated what we currently have. The latest fixes bugs, but eats up memory like crazy. It got 2% through the process, and had used up more than 25 GB of memory/swap. That puts us at needing more than a TB of memory to generate docs using it, unless my arithmetic is way off (always a possibility).

The fallback would be to look again at PHPDocumentor, which we didn't like much based on the output. It's had more activity lately, but we'd have to see if it runs through okay.

Within Installation, it sounds there's more to fill in/clarify about both local.config and module.config, especially overriding in local.config

Large parts of the two modules pages are identical... likely different vintage copies of the wiki or something similar

Underneath Modules is probably the preferable place for this to go.

As with API Request Options, [API Search Parameters] should have a defaults column.

Should cover:

• How to create theme configuration fields in theme.ini
• How to access theme configuration values and assets in the views

When I was writing CSSEditor and reading the Events documentation, I couldn't discern what class identifier(s) to use with view.layout.

The content of the forum post about updating modules to 2.0.0 is a perfect example of what should go there.

From the convo on omeka/omeka-s#1074 (comment)

This should go into the i18n documentation here.

This will likely call for @kimisgold consultation to lay out principles and structures

This omeka/omeka-s#852 should be added for module writers

Per this convo omeka/omeka-s#1171 (comment)

When I was thinking about using external libraries with my module, I couldn't find any documentation on best practices for including them.

The helpers folder, and what to put in config/theme.ini

Theming development needs more information

Currently, we guide toward the SQL statements for updating/migrating. But I don't immediately see where/how to invoke the event. That should be more prominent.

Also notable, the current docs are ant-based, which seems to be going the way of the dodo

hi there,

we are using omeka s in our library and a requirement for uploaded files (or URLs) appeared.

in order to show the right file version for the user, after he chooses the front end language, we need to catalog the file/URL language

curent field types dont allow this metadata to be inserted, so, would ther be any plugin to fulffill this requisit?

if not, what part of omeka source code need to be changed to allow this aditional descriptio for uploaded files

thanks!

Tutorial.

• Introduction: data types expand the ways users can describe content
• Explain interaction of data types, values, and templates: that every value has a type, and the templates determine what the type of new values is
• necessary elements: configuration keys, class, methods.
  • including the concept of not needing to do most of that in the common case of extending from one of the base data types

The gulp stuff in the migrations section is actually for core, not modules

What is the license for this repo?

The docs/modules/introduction.md page states that assets should be placed in an assets/ directory but Omeka S seems to only be looking for asset/.

Largely parallel content exists in the Modules and Key Concepts sections.

The Modules content is better-quality, but obviously is pitched from a module viewpoint. Still, this should be the bulk of what's kept, I think.

I set up my routes and navigation in module.config.php and couldn't figure out why they weren't working until I was advised to include getConfig() in Module.php. I don't think we currently have documentation on its usage.

The reorganization branch is an attempt to reorganize the docs in a more logical and intuitive fashion. This breaks internal links, but mkdocs can help us find and correct them. This also breaks the flow of some of the content, which we'll need to correct by proofing each page to fit into the new structure. We'll eventually have to change the order of the navigation, but that will have to wait until we finish organization.

But before I continue I need some eyes on the new organization. Does it make sense from a developer's perspective? A module developer? A theme developer?

- Omeka S Developer Documentation
- Contributing to Omeka S
- Debugging Omeka S
- For Omeka Classic Developers
- Registering an Addon
- Api
    - Introduction to the API
    - API Reference
    - REST API
- Configuration
    - Configuring Omeka S
    - Configuration Reference
    - Services and Factories
- Controllers
    - Introduction to Controllers
    - Controller Plugins
    - Routes and Navigation
    - ViewModel
- Events
    - Client Event Reference
    - Client Events
    - Server Event Reference
    - Server Events
- Miscellaneous
    - Access Control Lists (ACL)
    - Doctrine ORM
    - Forms
    - Internationalization
- Modules
    - Introduction to Modules
    - Data Model
    - Data Types
    - Media Ingesters and Renderers
    - Page Blocks
- Themes
    - Introduction to Themes
    - Sass and CSS
    - Style Guide
    - Theme Modifications
    - Theme Settings
- Views
    - Introduction to Views
    - Representations
    - View Helpers

There are some new pages that need content:

• "Introduction to the API": an introduction to the API and documentation for the programmatic API
• "API Reference": a reference for search criteria and request options
• "Introduction to Controllers": an introduction to controllers
• "Controller Plugins": a list of controller plugins and how to create one
• "Introduction to Views": an introduction to views

@zerocrates This is a slight departure from where we left off yesterday. I've added back in the "Modules" section because "Themes" is a separate section and the contents of the (now deleted) "Extending" section are specific to modules. I moved the "Introduction to..." pages to their respective "Modules" and "Themes" sections. Also, I'm particularly interested in getting your help editing the page content to fit into the new "flow" that the organization imposes. I don't have the time to do this alone.