Hi everyone,
I want to split this off into a separate discusion.
Currently I am working on the https://gnustep.github.io/ site. Does
anyone have any feedback on the structure of the site?
Also, it would be helpful if somebody could read the guides that I
currently have put on there.
The Linux instructions of "Installation and Setup"
<https://gnustep.github.io/Guides/Setup/index.html> is entirely new. The
Windows instructions and the manual building instructions for Linux are
from https://github.com/gnustep/documentation/ which was written by Hugo
Melder.
The "Building Apps with GORM" tutorial
<https://gnustep.github.io/Guides/App/index.html> is a combination of
Pierre's Dev Tutorial (written 2001 by Pierre-Yves Rivaille, updated
over the years until 2010) and from GSPT.
The "Building Apps from Code Only" tutorial
<https://gnustep.github.io/Guides/AppsWithCodeOnly/index.html> is based
on Nicos Drakos's and Ross Moore's "First Steps in GNUstep GUI
Programming" (written 1993-1999, posted on Nicola Pero's website)
I created new documentation for Make
<https://gnustep.github.io/APIRefs/Make/index.html>, including Nicola
Pero's tutorials and some new reference documentation, with parts copied
from the manual and from the source code. The reference documentation
really needs to be improved -- there are many paramaters that are not in
the texinfo Make manual, and my new documentation doesn't include all of
the commonly used project types.
I believe we need to make more conceptual and reference guides,
including topics such as:
* memory management (manual memory management, use of the GNUstep memory
management macros, using ARC, how ARC interacts with manually refcounted
code -- also, does the Boehm GC still work?)
* MVC paradigm
* The controls available in GUI
* The overall architecture of the project
* Deploying/packaging your code -- this is also something that needs a
lot of technical work so that we can have a single system to do this
across platforms
* How GUI takes input and interacts with Back
* API design guidelines
* The Objective-C programming language (I started on this at
https://ethanc8.github.io/NewDocumentation-ObjectiveC/)
Additionally, we need to build API references for all of our frameworks.
Some dependencies and useful external frameworks that don't have their
own documentation sites could also be hosted here, but some of them
don't have documentation. Libdispatch's documentation is scattered all
over the place, and libobjc2's ABI docs are incomplete and they don't
have many API docs.
I'd like to integrate the API docs with Sphinx, but for now I'm just
letting gsdoc/autogsdoc generate HTML and linking them to the
Sphinx-generated docs. What do you guys want our API docs to look like?
Doxygen-style? pgi-docs style
<https://lazka.github.io/pgi-docs/index.html#Gtk-3.0/classes/ComboBox.html#Gtk.ComboBox>
(I really like this one)? gi-docgen style
<https://docs.gtk.org/gtk4/class.ComboBox.html>? current Apple style?
2016 Apple style? ADC style? Microsoft Learn style? Like autogsdoc
generates now, except nicer-looking?
Is there anything else you think we need to document?
Thanks,
Ethan
