Project

General

Profile

Bug #8430

QFQ Doc mising

Added by Elias Villiger 4 months ago. Updated about 1 month ago.

Status:
Closed
Priority:
High
Assignee:
Target version:
-
Start date:
29.05.2019
Due date:
18.08.2019
% Done:

50%

Estimated time:
Discuss:


Related issues

Related to QFQ - Feature #8594: QFQ auf packagist registrierenNew2019-06-20

Associated revisions

Revision 014a3c4a
Added by Carsten Rose 4 months ago

Merge branch 'newdoc' into 'master'

Newdoc: docs.typo3.org seesm to fetch only the master branch - we need to merge to bring the doc online

See merge request typo3/qfq!147

Revision 628e480f (diff)
Added by Carsten Rose 4 months ago

Add various fields to composer.json

Revision c9f75c11 (diff)
Added by Carsten Rose 4 months ago

composer.json: fixed wrong 'type'

History

#1 Updated by Carsten Rose 4 months ago

  • Status changed from New to In Progress
  • wow, das ist der cloud Alptraum - ploetzlich ist alles weg.
  • Evtl. findest Du noch etwas unter .../typo3conf/ext/qfq/Documentation/html/Manual.html
  • Ich frage bei Typo3 nach was los ist.
  • Alles weitere unter hello.math.uzh.ch > QFQ

Alte Doc URL: https://docs.typo3.org/typo3cms/drafts/github/T3DocumentationStarter/Public-Info-053/Release.html
Neu Doc URL (temporaer): https://qfq.io/doc

#2 Updated by Carsten Rose 4 months ago

  • Status changed from In Progress to New

#3 Updated by Carsten Rose 4 months ago

Daniel Siepmann3:34 PM
https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocForExtension/Webhook.html#webhook

And also, your extension should probably not use a non stable url / draft as ofifcial documentation
better add your Manual to the extension, and publish it as expected
The hook story should be the same for GitLab and GitHub, I guess

Carsten Rose3:40 PM
@spoonerweb I removed the 'external doc' entry in the extension setting - now there is no link at all.

The reason is, your Manual is not part of the extension
3:42 PM
Martin setup the "Starter Manuals". These were not intended for production usage
3:43 PM
I'm a bit confused of the directory structure

Sybille Peters3:43 PM
The "official" way is: Add your documentation in a Documentation subfolder as described here: https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocForExtension/CreateFromScratch.html

Daniel Siepmann3:43 PM
The folder does exist, within "Extension". I guess the TYPO3 extension is a subpart of this project, and is published to TER
3:44 PM
That's not supported right now, and there are no plans to do so
3:44 PM
One way would be to use git subtree split to split the extension into an mirror repository, add the webhook there, and you should be done

Sybille Peters3:45 PM
clarification about the "starter manuals": They were created as a way to get started and be able to render online while editing with minimal setup effort on your machine. You used to have to install sphinx locally. Now, we have the Docker image. Nowadays, we recommend to render locally with Docker.
3:46 PM
As Daniel said: Not really meant for production.

Carsten Rose3:47 PM
In general I'm happy to follow the official way - I'm just not aware that I was wrong.
3:47 PM
@danielsiepmann that would be great

Daniel Siepmann  May 29th at 3:49 PM
I guess your setup is a bit special. As mentioned before, you have a larger project within your repository, and TYPO3 extension is a smaller part within this repository?

Daniel Siepmann8:22 PM
Okay, das ist im Prinzip das gleiche wie das Rendering ;)
8:22 PM
Zumindest so wie ich das aktuell sehe, das wäre beides mit einem Schlag erledigt
8:25 PM
Mein Vorschlag wäre in eurem GitLab CI nen git subtree split auf den Extension Ordner zu machen.
Der schiebt dann die Extension in ein eigenes Repo. Das kann dann meinetwegen in eurem GitLab sein, oder direkt GitHub. Das wäre dann ein "mirror". So wie bei TYPO3. Da gibt es ja das offizielle Repository, und die hier: https://github.com/TYPO3-CMS/

Da sind alle System Extensions einzeln zu finden, als mirror, automatisch gesplittet.
8:25 PM
Die sind aber "self contained", mit composer.json und Dokumentation und webhooks auf GitHub
8:25 PM
Der Hook triggert das rendering, und packagist: https://packagist.org/packages/typo3/cms-core (edited) 
8:25 PM
Somit habt ihr euren alten Workflow, und supported alles andere

Carsten Rose8:26 PM
Das die doc mittels docker gebaut wird  ist klar - aber wie kommt sie dann in's ter? zusammen mit dem ZIP upload?

Daniel Siepmann8:27 PM
das TER ist davon unabhängig
8:27 PM
Zum Splitten kannst du dir hier einmal ansehen wie das TYPO3 selbst macht: https://bitbucket.typo3.com/projects/INT/repos/intercept/browse/src/Service/CoreSplitService.php#132
8:27 PM
Das publishen ins TER kannst du automatisieren. Das hat nix mit der Doku zu tun. Das TER prüft immer ob es ne Doku gibt, und zeigt die dann an

Carsten Rose8:28 PM
Ich muss nochmal zurueck zum Anfang: wo sollte die Doku zu einer Extension liegen, so das jemand der sich die Extension runter laedt darauf zugreifen kann?

Daniel Siepmann8:29 PM
Da wo ihr die gerade habt. Ihr habt die Struktur der Extension sauber
8:29 PM
Das Problem ist, das eure Extension im Unterordner eures Repo liegt

Carsten Rose8:31 PM
Gut, desweegen machst Du ein split. In dem Repo ist dann die composer.json inkl. dem Subfolder 'Documentation'?

Daniel Siepmann8:31 PM
Genau, das repo hat dann alles was in dem Unterordner ist, also ne saubere Extension
8:31 PM
die kann man dann sauber per composer laden, und auch sonst nutzen

Carsten Rose8:34 PM
wo muss ich die github / gitlab URL vom doc project eintragen, so dass im Ter nicht mehr steht 'External Manual', sonder 'Manual'? (edited) 

Daniel Siepmann8:35 PM
Nirgendwo. das TER schaut bei docs.typo3.org nach. Sobald deine Doku da ist, sollte das gehen (ggf. gibt es da noch nen Bugfix)
8:35 PM
Das bedeutet, sobald der Split durch ist, und du die Extension auf GitHub (oder GitLab) hast, kannst du dort den Webhook der Doku eintragen
8:35 PM
https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/WritingDocForExtension/Webhook.html

Carsten Rose8:36 PM
ahh, webhook, alles klar.
8:38 PM

#4 Updated by Marc Egger 4 months ago

  • Assignee changed from Carsten Rose to Marc Egger

#5 Updated by Marc Egger 4 months ago

  • Status changed from New to In Progress

#6 Updated by Carsten Rose 4 months ago

Marc hat den Branch 'newdoc' angepasst:

  • mit 'make doc-local' wird ein lokaler Docker Container mit T3 Sphinx angeworfen. Damit kann einigermassen zuegig das finale Ergebnis angeschaut werden.
  • in Zukunft soll ein push auf git mit einem Tag dafuer sorgen das eine neue Doku docs.typo3.org gerendert wird.

CR hat 'newdoc' bereits in Master gemerged: docs.typo3.org hat mit Gitlab Webhooks noch Probleme und immer nur 'master' ausgecheckt - in 'Master' war das composer.json aber nicht am richtigen Platz und alles schlug fehl.

Im composer.json fehlten noch ein paar Angaben - nachdem diese nachgefuehrt waren wurde die Docu auf docs.typo3.org gebaut.

#7 Updated by Carsten Rose 4 months ago

  • Due date set to 08.06.2019

#8 Updated by Marc Egger 4 months ago

  • Description updated (diff)

#9 Updated by Marc Egger 4 months ago

  • Description updated (diff)

#10 Updated by Carsten Rose 3 months ago

  • Tracker changed from Support to Bug
  • Subject changed from QFQ Doku nicht mehr verfügbar to QFQ Doc mising

#11 Updated by Marc Egger 3 months ago

  • Due date changed from 08.06.2019 to 30.06.2019

#12 Updated by Carsten Rose 3 months ago

#13 Updated by Marc Egger about 2 months ago

  • Due date changed from 30.06.2019 to 18.08.2019

#14 Updated by Marc Egger about 1 month ago

  • Status changed from In Progress to Closed

- Link zu Dokumentation erscheint in TER nich automatisch > habe link manuel eingestellt. Loesung ist ok.
Neuste Version von QFQ und Dokumentation sind auf TER

#15 Updated by Carsten Rose about 1 month ago

Super - vielen Dank Marc.

Details dann am Donnerstag.

Also available in: Atom PDF