pkp / pkp-docs Goto Github PK

A number of the properties we use in the schema lead to validation errors. The swagger UI automatically places a button at the bottom of the docs that links to the validation status:

https://online.swagger.io/validator/debug?url=https%3A%2F%2Fdocs.pkp.sfu.ca%2Fdev%2Fapi%2Fojs%2Fdev.json

Try to strip out the unwanted properties and display the validation status (which we will hide for now).

The images for the category settings under the Journal Settings section of Learning OJS 3 are not loading:

https://docs.pkp.sfu.ca/learning-ojs/en/journal-setup

Code in the Passing Data to Templates page is not correctly indented.

pkp/pkp-lib#3404 (comment)

In the Architecture > Modules section, the dev docs describe the Article and Submission classes. In v3.2, these have been changed to Submission and PKPSubmission.

https://docs.pkp.sfu.ca/dev/documentation/en/architecture#modules

Example: /admin-guide/en/definitions.html

The query parameters and response models don't load. Looks like an issue with the 3.1 json file. This may need some manual fixing up.

Add an example plugin that makes a custom citation style available. Partial code here: pkp/pkp-lib#4851 (comment)

The table heading styles could be improved slightly (left-aligned). And on small devices the table forces the viewport width wider than the screen, so it would be good to try and handle that a little better.

Table at https://docs.pkp.sfu.ca/learning-ojs/en/settings-workflow#emails

The What Is A Theme -> HTML/Smarty Templates page concludes with a link for information about loading "custom data", but there is no page at that URL.

Add information about testing and documentation to the plugin guide. And add testing and documentation to the plugin template.

WordPress creates "field guides" for each major release, which is like a short-hand guide for developers on the major things that have changed (technical changes). I'd like to start doing something similar from v3.2 onwards.

This is a list of things that should be documented in such a guide for v3.2:

• Versioning.
  • Submission/Publication split.
  • Publishing/unpublishing workflow
  • STATUS_SCHEDULED
  • ASSOC_TYPE_PUBLICATION
• New API endpoints (just link to new REST API guide)
• New forms
• Theme options now support all form field types (except uploads)
• $activeTheme now available #194
• Stats service
• Submission/Publication services
• PublishedArticle / PublishedMonograph are gone. Article and Monograph are now Submission. (Same with DAOs.)
• getMany now returns an iterable object instead of an array
  • No array_map
  • Can't rewind
  • Use $submissionsIterator = Services::get(...)->getMany(...)
  • Use count($submissionsIterator) instead of !empty($submissionsIterator)
• New signed_page_key_secret for unsubscribe
• Changes to EntityReadInterface and new EntityQueryBuilderInterface. pkp/pkp-lib#5354
• Application::getRequest() to Application::get()->getRequest() #187

When using the longer documents/guides and reading the longer sections, it feels cumbersome to have to scroll back to the top of the page to access the table of contents and go to a different section/chapter. It can also be hard to find the section of the TOC that you're in when you scroll back up. I think the longer guides would be easier to use if there was a floating table of contents that you could continue to see as you move down the page, centred on whatever section you're currently reading.

This would make it easier to make a distinction between the guide's body text and possible text in the screen shot.

@NateWr example:

Can we use Jekyll documents for this?

Add a link to each page which prompts the reader to submit an improvement. It should link to GitHub to automatically open a PR like here:

https://flight-manual.atom.io/getting-started/sections/why-atom/

Those guides which have only a single language probably don't need a landing page. We can link directly to the document in English. For example:

Instead of having a /translating-guide page, we can remove that and just link directly to the /translating-guide/en page.

From v3.2, an $activeTheme variable is available in every template. This can be used to get the value of theme options: $activeTheme->getOption(...).

This information should be added to the Theme Options API in the theming guide.

See https://forum.pkp.sfu.ca/t/ojs-3-editorial-process-videos-in-french/55509

It would be great to link to these somewhere in our Learning OJS docs!

As discussed in Slack, we'd like to add a link icon to the headings that contains the link to that section, e.g:

Here are a couple of other examples:

• https://wordpress.org/support/article/how-to-install-wordpress
• https://www.drupal.org/docs/user_guide/en/understanding-modules.html

When v3.2 is released, we should change the code to access the request through the application in the theming guide's page on passing data to a template: https://docs.pkp.sfu.ca/pkp-theming-guide/en/advanced-custom-data.

Where it says:

$request = Application::getRequest();

Should be changed to:

$request = Application::get()->getRequest();

(Note, this shouldn't be changed before 3.2 is released.)

I've been running into the following error when attempting to build the docs on our production server:

Conversion error: Jekyll::Converters::Scss encountered an error while converting 'css/style.scss':
                    Invalid US-ASCII character "\xE2" on line 46

I don't see this error when building locally; it could be some sort of jekyll build or config issue. It can be solved though by adding the following line to the top of css/style.scss:

@charset "UTF-8";

Any objections to adding this permanently to the repo?

See: mmistakes/jekyll-theme-hpstr#185 etc.

When versioning is complete and v3.2 is released, we should add information about working with versions to the theming guide.

There should be a link to the downloads page
https://pkp.sfu.ca/ojs/ojs_download/
somewhere in the install documentation.

More than one person in the forums has mistakenly used the Github download in lieu of the download page being difficult to find. The link isn't in the linked README either.

Right now we encode lang="en_US" into the <body> tag. We need some way to support alternate languages, and particularly RTL (right-to-left) languages such as Arabic, Hebrew and Farsi.

The obvious way is to use frontmatter, which we may need to do if we ever want to get a reasonable search going. But that could get cumbersome to maintain. Maybe we can look for locale directories in the path of each page (eg - .../en/...)?

I noticed that all of the screenshots for the guide to using payment show OJS 2. Should this resource be listed under the OJS 2 section, @AhemNason?

In new installs, under "General Settings" of the config.inc.php file, the default setting should be installed = Off but in case you are copying an existing OJS/OMP directories, this might be installed = On. Just something to look out for when/if installing.

Get Sophy to generate one in-line with the forum and other logos we have.

Developers should get a special hub dedicated to working with pkp-lib.

We accidentally uploaded the wrong example as a "DO" in the last part of the homepage image section

It should be:

The PDF icon for the GDPR guide is still showing up on the TOC.

• File structure for docs for old versions of OJS 3
• UX pattern for identifying versions

The api_secret_key must be set in config in order to use the apiToken.

Now that the Arabic translation of Using Paypal (OJS 2) is working, we should link to it from the card on the homepage. Here's a diff showing how that can be done:

diff --git a/_includes/cards/ojs2/using-paypal-for-ojs-and-ocs.md b/_includes/cards/ojs2/using-paypal-for-ojs-and-ocs.md
index 3db23e3..a5f030b 100644
--- a/_includes/cards/ojs2/using-paypal-for-ojs-and-ocs.md
+++ b/_includes/cards/ojs2/using-paypal-for-ojs-and-ocs.md
@@ -2,3 +2,7 @@
 ### [Using Paypal (OJS 2)](/using-paypal-for-ojs-and-ocs/en/)
 
 How to configure OJS 2 to use Paypal. [View Now](/using-paypal-for-ojs-and-ocs/en/)
+
+---
+
+<span class='fa fa-language'></span> Available in [العربية](/using-paypal-for-ojs-and-ocs/ar/).

Force break words in links to fix this.

• PKP logo
• Link to PKP
• Link to docs hubs
• Link to support forum

The API docs say to use ?apiKey=... for authentication, but it's actually ?apiToken=....

Usage of lower/uppercase in file extensions should be more consistent since it can break images (e.g. .png vs .PNG).

Admin manual is still missing XML samples from here: https://pkp.sfu.ca/wiki/index.php/Importing_and_Exporting_Data#Creating_the_XML_Import_File - I'll revisit this issue and fix this.

From Antti-Jussi:

noticed that here: https://docs.pkp.sfu.ca/learning-ojs/en/authoring

It says "To make a submission to an OJS 3.1 journal, you will first need to register as an Author (see Registering with a Journal). After that, when you login, you will be taken to your Dashboard."

As of 3.1.1.2 that of course is not true anymore, you just need a user account and you can obtain the role during the submission process.

(also the link there is broken)

This issue will be used to track progress on the main developer documentation content, as well as store some notes for unfinished sections.

• Introduction
• Getting Started
• Architecture
  • Request
  • Routes
  • Handlers
  • Authentication
  • Authorization
  • Services
  • Entities
  • Database
  • Plugins
• Frontend
  • Link to theming guide if they're just looking to theme.
  • Template Manager
    • Always escape in smarty templates unless you have a good reason not to
    • Add note about {debug} smarty feature
  • UI Library
    - reset focus after modal is closed
    (and generally about kicking off something)
    • How to mount a grid inside of a Vue component and refresh it.
    • How to load a modal
  • Components
  • Controllers
    • (deprecated)
• Utilities
  • Application
  • Cache
  • Config
  • Email
  • File
  • Hooks
    • Return false in a hook to allow other hooked functions to run.
    • hook priorities
  • Notifications/Logs
  • Translation
    • How locales work (supportedLocales, supportedFormLocales, supportedSubmissionLocales, fallbacks)
  • Updates
  • Validation
• Resources
  • Postman API file
  • GenerateMetrics tool
  • GenerateSubmissions tool
  • How to create a URL to what you want (included in architecture)
  • How to build API docs to match your build
  • Glossary of terms? (Context, Galley, ...)
  • CacheBuster plugin
  • Vagrant
  • Code Standards
  • Technical Reference: http://pkp.sfu.ca/ojs/docs/technicalreference/2.1/
  • No generated hook names or locale keys
• Other
  • Email
  • Metrics
  • ASSOC_TYPE
  • Tests
    • how to do do a submodule commit to get the tests running
    • how to get the tests running locally
  • Versioning (when merged to master). resources: Versioning

Several pages in the OJS 2 book are still linking to the old gitbook docs, e.g. https://docs.pkp.sfu.ca/learning-ojs-2/en/layout_editors

See all results here: https://github.com/pkp/pkp-docs/search?q=pkp.gitbooks.io&unscoped_q=pkp.gitbooks.io

Add a Plugin Guide like the Theming Guide.

Suggested outline:

• Intro

• Blocks

• Import/Export

• Reports

• Themes

• Generic

• Other

• Packaging a plugin, getting it on the plugin gallery

• Examples

  • Adding field to form/schema
  • Routing request to own handler
  • Theming

As discussed at yesterday's DIG meeting, it would be great to have a mechanism for users to submit feedback on the docs hub. This could be done as an embedded form.

A single-page guide should generate and display a table of contents based on the heading structure.

The card highlights work best when only one card is highlighted per hub. With more than one, the eye doesn't know where to settle and we lose the benefit of highlighting.

Generally, larger cards will be more prominent. So one solution here would be to create a section for the links which will increase the card's presence in the list:

If that's not enough, I could implement a banner-like display:

pkp/pkp-lib#3691