Looking for volunteers to build a reference manual for edx-platform đŸ’Ș

Working Groups Build-Test-Release
1

I recently opened this PR, which is a work-in-progress: https://github.com/edx/edx-platform/pull/23183

My goal, and one we discussed as part of the build/test/release working group, is to create a reference manual for edx-platform, and later for all other Open edX services. This is groundwork that is a strong requirement before the working group can even start talking about crafting the named releases.

As you guessed, there is a lot of work involved :wink: which is why we need you! We are looking for early feedback on these docs: what would you like to find there? what is the best format and layout? can you write some of the docs?

If you’d like to contribute, I’ll be more than happy to add you to the openedx-btr-wg organization on Github. You can then directly push your changes to the PR. Just send me a personal message with your Github nickname.

Also, feel free to hack this topic to post your comments as much as you want :alien:

3 Likes
2

@nedbat As you know, I’m having trouble documenting the FEATURES variable from the edx-platform settings, using only standard tooling from sphinx and autodoc. I recently realised it would be much easier to document this variable if it were a separate module or a class with static attributes. Also, I think it would be an improvement over a dict, as is illustrated by this example:

if settings.FEATURES.get("ENABLE_THINGY"):
    do_something()

In that example, when the “ENABLE_THINGY” feature is removed or renamed, the code keeps working, but the do_something function is no longer called. I think it would be better if this code raised an error, as we would get with:

if settings.FEATURES.ENABLE_THINGY:
    do_something()

What are your thoughts? There are 1300 calls to FEATURES in edx-platform, so it would be a rather big PR, but if you agree then I can get started. I can always keep the .get() interface to maintain backward compatibility:

class FEATURES:
    ENABLE_THINGY = False
    ...
    @classmethod
    def get(cls, name, default=None):
        return getattr(cls, name, default)
1 Like
3

We talked about this problem a bit last week. I think the consensus was that namespacing all the “features” into FEATURES wasn’t actually gaining us anything. No one could explain what should go in FEATURES, and what should be a top-level Django setting.

So how about just dumping the whole dictionary into the Django settings?

4

Sounds good to me! Maybe I’ll namespace the features in a specific module though. I’ll think about it.

5

Let’s get more ideas/opinions on the table before a big pull request
?

6

I’ve done some prototyping for moving FEATURES to a dedicated module or unloop it in the settings. It’s tedious, but completely doable. However, this is a rather big change and I’d rather avoid solving both questions at the same time. I think it’s best if we open a separate PR to migrate the FEATURES settings and document them. Can I suggest we focus on documenting other settings for now? I’ll work on improving my PR.

7

That’s a great idea overall!

Documenting all the settings is really nice and I personally prefer to document it near the code instead of a separated text file (like Django project do), it keeps it easier to maintain.

My main worry is that as a newcomer developer it already feels like the documentation is a bit scattered between the edx-developer-docs, docs.edx.org and the repository docs. At first glance it doesn’t look like a very well maintained documentation and doesn’t seems to be truthlike. Maybe at a first step we should discuss about how this new resource will be accessible compare to the existing ones because the better the documentation is written if it is not easily readable, it won’t be very useful.

I understand that it is a bit out of scope of the build/test/release working group but, that’s my two cents. :slight_smile:

8

Thanks for your answer @toxinu! I agree that the docs are too scattered and not very well organised. Fixing this is a rather big task in itself and it would be the working group’s job to do this; unfortunately, 1) we’re spread thin at the moment and 2) I do not have access to the deployment scripts that edX uses to deploy those docs. Thus, the best I can do for now is to improve the docs in the edx-platform repo and host them myself. For instance, this is the result of the ongoing PR: https://docs.openedx.overhang.io/reference This is very much a work-in-progress of course.

I added a few DOCUMENTME tags here and there in the pull request. Everyone in the BTR working group should feel free to add commits to this PR to replace those tags, or add a few more.

1 Like
9

By the way @nedbat I think it would make sense to integrate the API docs to the reference manual, so I think I’ll just merge the two. Any objection?

10

Actually, I was about to comment on this. I think “Reference Manual” is too broad a term. I don’t see the point in having one book that covers both REST API docs and settings/deployment docs. Why don’t we keep it simpler, and call this the “Settings/Deployment Reference Manual”?

11

Naming is one of those hard and important things :slight_smile: How we name this manual will impact what we actually put in it.

My vision for this manual is “the thing that developers and platform administrators will turn to to figure out what does what in edx-platform”. Also, what goes into this manual is what should be considered sufficiently important that we should keep track of changes made to its content. API docs fits both these criteria: developers want to have a reference of API endpoints (and the existing docs are great for that) and they want to be informed of changes made to the API docs.

Admittedly, the API docs is more developer-oriented, and the settings and operational command docs are more administrator-oriented. But this is a narrow distinction: in practice, developers are also in charge of deploying the platform, and vice versa.

Also, it’s just more convenient to have a unified ./docs folder that contains a single sphinx project. It makes it easier to compile and deploy the docs.

This question is yet another one of those where I have a strong opinion, but I don’t think it’s a big deal if we don’t do things my way. So if you’d rather keep the API and the settings/operational docs separated, I’m fine with that. But then we need to find a more concise name than “Settings/Deployment Reference Manual”. Something like “edx-platform developer/administrator handbook” – but better.

1 Like
12

@toxinu @sambapete @BbrSofiane @jmaupetit @morenol @jramnai Hi! :wave: You guys mentioned before that you were interested in contributing to the build/test/release working group. As you may already know, I have started a pull request on edx-platform to kickstart the documentation effort: https://github.com/edx/edx-platform/pull/23183 I would like you to help document the settings and operations involved in the deployment of Open edX (more specifically: edx-platform). To do so, I would like you to add commits to this PR.

Are you guys still interested in this? Does the current containment situation somehow limit your work capacity? (it does affect mine) If you don’t think this pull request is relevant, why?

I would like to have feedback from everyone. As far as I am concerned, a simple “I don’t have time for this at the moment” is enough. I just need to know who would like to be really involved and what limits your participation.

1 Like
13

:wave: @regis! I’m truly sorry for my lack of responsiveness, but as you expected, since a few weeks now, our house became a noisy school and playground for our kids. And this really impact my work capacity :wink:

Apart from parenting, we also have new high order priorities at FUN to handle our increased traffic and requests from the french government
 so yeah, I don’t have much time to help you or provide relevant feedback at this time.

BTW, thank you for your great work! :muscle:

14

From the start I was willing to participate as a reviewer for the documentation and I was mostly interested by the build, test and release. I may be totally wrong on this, but it is becoming the documentation / build / test / release group.

But I clearly understand the importance of documenting in order to build, test and release.

15

@regis Sorry for the radio silence! Yes, the last couple of weeks have been hectic as we had to re-think our strategy for the next couple of weeks.

Fortunately, online content is at the center of it. I am definitely interested in contributing. I will catch up on the work in the next couple days (will probably message you on slack at some point).

16

Hi @regis :raised_hands:
Last weeks at OpenCraft we tackled some Juniper related bugs but hopefully we will have more time to contribute to the documentation very soon. :slight_smile:

Thanks a lot for your effort!

17

Hi @regis, I have been in other tasks the last weeks so I haven’t had time to take a look at this but I think that this PR is pretty much relevant.

I am going to check the current status of the PR and I am going to add my thoughts tomorrow or the early days of the next week.

Thanks

18

Thanks everyone for your quick reactions, I appreciate it! It’s OK if you are not available for working on the reference docs; as Juniper is around the corner, I’m sure we’ll have other opportunities to work together really soon :slight_smile: