Documentation review and improvements about reel2bits HOT 22 OPEN

Okè.

I add for the record that the documentation is (for now) built from the docs directory of the frontv2 branch.

from reel2bits.

Ok, i'll add a s to apps developments to clarify this slightly.

from reel2bits.

I set up Sphinx and the doc build. The use of the .. warning:: take in place of .. important:: seems better.

from reel2bits.

I need to switch to the double backtick.

@rhaamo this is work in progress on the proofreading branch.

from reel2bits.

@rhaamo in /docs/features.rst, when you write :

The backend shares some APIs used by Mastodon, so app development can be simplified a bit.

...you mean it in a general way for all apps or for real2bit only?

from reel2bits.

Our frontend does use some parts of the mastodon API we implements, so a third party app could use them too.
Like we share the same authentication endpoints and profile retriewal, perhaps timelines too (even if the objects contains extra attributes).

from reel2bits.

In the Cache setup (Redis) section of /docs/installation/external_dependencies.rst, I don't understand why there is a list item after the first sentence:

reel2bits also requires a cache server:

• To handle asynchronous tasks such as music transcoding or some ActivityPub tasks

Since the list is only one item long, either some other lists items where planed, either the list could be removed 🤔

from reel2bits.

list can be un-listed, nothing really planned (for now)

from reel2bits.

If the documentation software could highlight the Important blocks a way similar to the way the Note blocks are highlighted, I think it could help very much.

For now, the Note blocks are in a grey rectangle, but Important ones are on a white background. I think they could be missed and they would require something like orange or red background or something (if Sphinx allows something like custom CSS etc.)

from reel2bits.

we use a theme, I don't really know if we can merge a css without doing anything ugly.
I will look at that later.

from reel2bits.

Maybe by using .. warning:: , not .. important:: ?

from reel2bits.

maybe, gonna try later

from reel2bits.

• Features
  • Scope
  • Structure
  • Federation
• User Documentation
  • Getting Started
  • Using reel2bits
  • Troubleshooting Issues
• Administrator Documentation
  • Setup Guides
  • Administration
  • Troubleshooting Issues
• Contribute to reel2bits development
  • Quick summary of the various stacks / libraries we use
  • A quick path to contribute on the front-end
  • Setup your development environment
  • Working with federation locally
  • Typical workflow for a contribution
  • Internationalization
  • Contributing to the Backend API
  • Contributing to the front-end
• Translating reel2bits
  • Translation workflow
  • Guidelines
  • Submitting a new language
  • Requesting a new language
  • Extracting messages from source

from reel2bits.

maybe, gonna try later

@rhaamo I'll take care of it

from reel2bits.

By the way, does the guillotina Sphinx theme dependency needs to be declared somewhere? I had to install it by hand, maybe it should be added in the requirements.txt?

Before doing this, the doc building failed:

./serve.py                                                                                                                                        
Running Sphinx v1.6.7                                                                                                                                                                   
                                                                                                             
Exception occurred:                                                                             
  File "conf.py", line 191, in setup                                                                                                                                                              
    import sphinx_guillotina_theme                                                                                                                                                                
ModuleNotFoundError: No module named 'sphinx_guillotina_theme'

from reel2bits.

Just a note to myself:
I've used some `xxx` instead of ``xxx`` for like paths in the recent diffs (configuration), I need to switch to the double backtick.

from reel2bits.

Before doing this, the doc building failed:

./serve.py                                                                                                                                        
Running Sphinx v1.6.7                                                                                                                                                                   
                                                                                                             
Exception occurred:                                                                             
  File "conf.py", line 191, in setup                                                                                                                                                              
    import sphinx_guillotina_theme                                                                                                                                                                
ModuleNotFoundError: No module named 'sphinx_guillotina_theme'

@smonff pip3 install sphinx-guillotina-theme sphinx, not sure it's documented, only in the CI

from reel2bits.

updating my old instance and here is some (french) things I've thought:
la partie install devrait conseiller de export APP_SETTINGS='config.production_secret.Config' ou truc du genre pour que les commandes flask utilisent la bonne conf
voir de mettre ça dans ~/.profile de l'user qui run l'appli

les commandes flask doivent être lancés depuis le dossier api
pas sur que ce soit super explicite dans la doc suite au split api/front

from reel2bits.

apt-get install gettext-base devrait être rajouté dans les trucs a installer dans la partie installe linux
(fournit envsubst pour la config du reverse proxy)

from reel2bits.

todo moi: la partie non-docker du reverse-proxy est pourrie

from reel2bits.

les chemins des services systemd matchent pas la doc (virtualenv), todo moi : corriger les services, et supprimer les 'xx' du app settings

from reel2bits.

self todo again: add documentation about what we federates and how, and endpoints we uses (actors, activities, boxes,...)

from reel2bits.