Docs: cleanup of old/deprecated documents #7994
Conversation
humitos
force-pushed
the
humitos/documentation-cleanup
branch
from
38bc7a0 to
9731da6
Compare
|
|
||
| There are several settings used to configure usage of virtual machines: | ||
|
|
||
| DOCKER_ENABLE |
There was a problem hiding this comment.
It seems we are losing these docs? We should probably migrate these to the settings docs.
There was a problem hiding this comment.
I didn't find them relevant, that's why I delete this page completely. On the other hand, I don't think that using DOCKER_ENABLED=False works. I want to remove all mentions to settings that we don't normally use and/or we don't officially support. All of these just confuses users/contributors, unfortunately.
I moved DOCKER_LIMITS to the settings page because is still useful for local development and, in fact, a user needed/asked about it some weeks ago.
There was a problem hiding this comment.
One thing I don't understand: it seems that DOCKER_ENABLED is used in a couple of places:
$ grep DOCKER_ENABLE . -r --exclude=*.pyc
./docs/development/buildenvironments.rst:DOCKER_ENABLE
./docs/development/buildenvironments.rst: Default: :djangosetting:`DOCKER_ENABLE`
./readthedocs/projects/tasks.py: if settings.DOCKER_ENABLE:
./readthedocs/projects/tasks.py: if settings.DOCKER_ENABLE:
./readthedocs/projects/tasks.py: if settings.DOCKER_ENABLE:
./readthedocs/doc_builder/environments.py: If :py:data:`settings.DOCKER_ENABLE` is true, build documentation inside a
./readthedocs/settings/base.py: DOCKER_ENABLE = False
./readthedocs/settings/docker_compose.py: DOCKER_ENABLE = True
Does that mean that we should remove it from the code too?
There was a problem hiding this comment.
(This applies to DOCKER_ENABLED since you mentioned that perhaps it doesn't work - I get that there are other variables that do their job, but we want to avoid confusing users anyway)
There was a problem hiding this comment.
We are using DOCKER_ENABLED. However, the only value that works is True.
Some time ago, we used to support DOCKER_ENABLED=False and in that case we didn't use Docker to build documentation but we used the host packages (latex, pip, python, etc). However, using False now is completely broken and it confuses contributors.
IMHO, removing it from the documentation is the first step. The next one is remove all the code for the case when it's False; but it's outside the scope of this PR.
There was a problem hiding this comment.
We should at least open a ticket with a TODO removing this setting, then.
| .. TODO: expand this section explaining there the PR is automatically built and | ||
| the author can visualize changes without installing anything on their system. | ||
| However, if there is going to be periodic/bigger contributions, it may be a | ||
| good idea to install the Sphinx requirements to build our docs. |
There was a problem hiding this comment.
We can't just delete the mention of Sphinx here? Isn't this just making our docs worse and more confusing for new contributors?
There was a problem hiding this comment.
IMO, I would just mention that people can just edit the files directly on GitHub and create a PR that automatically does the preview.
If there is going to be a bigger contributing at some time, we can write this guide at that point 😄
There was a problem hiding this comment.
In fact, isn't it weird to have a "Contributing to Documentation" document under "Developer documentation" if we want to avoid referencing local installation instructions here? Perhaps we should move this to some other section, expand the content guidelines, and refer to development/standards for further information. But definitely not in this cleanup PR?
There was a problem hiding this comment.
@astrojuanlu I agree. In fact, we do have a "Contributing to Read the Docs" (https://docs.readthedocs.io/en/stable/contribute.html) and we have a section for "Contributing to Documentation". Probably improving that section is a cleaner path to move forward.
There was a problem hiding this comment.
Yea, I think it's a bit chicken & egg, since we want it to live with "contributing", which mostly makes sense under dev docs. Not sure the best way to structure this.
| @@ -46,13 +66,6 @@ Default: :djangosetting:`RTD_INTERSPHINX_URL` | |||
| This is the domain that is used to fetch the intersphinx inventory file. | |||
| If not set explicitly this is the ``PRODUCTION_DOMAIN``. | |||
|
|
|||
| MULTIPLE_APP_SERVERS | |||
There was a problem hiding this comment.
This is still in the code in some places. We should remove it from there as well.
I think #7044
docs/development/standards.rst
Outdated
| @@ -1,6 +1,9 @@ | |||
| Development Setup and Standards | |||
There was a problem hiding this comment.
If this is the new "install" doc, we should rename this file and move the standards bits to the bottom. Calling this standards.rst but having it be the install docs feels weird.
There was a problem hiding this comment.
We should do it as part of this PR, since we're removing the install doc.
- Remove `/development/install` page and redirect it to `/development/standards` - Remove `/custom_installs/` folder since we don't support it and those documents are completely broken - Remove `/development/buildenvironments` due that it's not valid anymore - Update Front-End page to mention `inv docker.buildassets` instead - Do not mention "Installation guide" when contributing to documentation - Put our design documents at the bottom of the list in the index - Put `/development/standards` at the top of the list in the index - Remove Elasticsearch manual installation: users shouldn't use this - Remove `MULTIPLE_APP_SERVERS` setting - Move explanation for `DOCKER_LIMITS` settings into settings page
We are promoting the usage of Dockr compose as the standard way of contributing/developing.
humitos
force-pushed
the
humitos/documentation-cleanup
branch
from
9731da6 to
9b1866c
Compare
|
I updated this PR with the feedback that I received and it's ready to re-review. |
| Make sure to apply it to the "Site". | ||
|
|
||
|
|
||
| Core team standards |
There was a problem hiding this comment.
I think we can simplify or remove this section as everything that is mentioned is done in docker already.
There was a problem hiding this comment.
I think it's worth noting this stuff in terms of architecture, but not necessarily in the install doc. I think it's fine tho.
There was a problem hiding this comment.
I'll keep it here for now. However, I'd be 👍 on moving this into the https://docs.readthedocs.io/en/stable/development/architecture.html together with a nicer graph there.
|
@humitos In the future it would be better to just push new commits here instead of rebasing and force pushing. I can't easily see whats changed since the last review, which makes reviewing the changes much harder. |
@ericholscher yeah, sorry. This was a mistake. I usually use force push only if there is no reviews already. I got fat fingered with all the Emacs hotkeys, you know 🙃 |
- development/install is now the want that we want people to find easily - custom_installs/* does not exist anymore
|
I just created the redirect. |
/development/installcompletely/development/standardspage to/development/install/custom_installs/folder since we don't support it and those documents are completely broken/development/buildenvironmentsdue that it's not valid anymoreinv docker.buildassetsinstead/development/installat the top of the list in the indexMULTIPLE_APP_SERVERSsettingDOCKER_LIMITSsettings into settings pageI limited this work to remove old/confusing stuffs for now, but there some sections that could be improved a lot by communicating exactly what we need.