Skip to content

Commit 53d1c03

Browse files
williamFalconwilliamFalcon
authored
Docs clean up 1/n (#12477)
1 parent dd0c40e commit 53d1c03

File tree

8 files changed

+310
-20
lines changed

8 files changed

+310
-20
lines changed

‎.github/CODEOWNERS

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
/.github/*.md @edenlightning @williamfalcon @borda
1818
/.github/ISSUE_TEMPLATE/ @edenlightning @borda @tchaton
1919
/docs/source/conf.py @borda @awaelchli @carmocca
20+
/docs/source/index.rst @williamfalcon
2021

2122
# Packages
2223
/pytorch_lightning/accelerators @williamfalcon @tchaton @SeanNaren @awaelchli @justusschock @kaushikb11

‎docs/README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,21 @@ Notes (Optional):
5959
- You need to have LaTeX installed for rendering math equations. You can for example install TeXLive by doing one of the following:
6060
- on Ubuntu (Linux) run `apt-get install texlive` or otherwise follow the instructions on the TeXLive website
6161
- use the [RTD docker image](https://hub.docker.com/r/readthedocs/build)
62+
63+
## Developing docs
64+
65+
When developing the docs, building docs can be VERY slow locally because of the notebook tutorials.
66+
To speed this up, enable this flag in before building docs:
67+
68+
```bash
69+
# builds notebooks which is slow
70+
export PL_FAST_DOCS_DEV=0
71+
72+
# fast notebook build which is fast
73+
export PL_FAST_DOCS_DEV=1
74+
```
75+
76+
## docs CSS/theme
77+
78+
To change the CSS theme of the docs, go [here](https://github.com/PyTorchLightning/lightning_sphinx_theme).
79+
Apologies in advance... this is a bit complex to build and requires basic understanding of javascript/npm.

‎docs/source/advanced/precision.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@
66
.. _amp:
77

88

9-
#########
10-
Precision
11-
#########
9+
###############
10+
N-Bit Precision
11+
###############
1212

1313
There are numerous benefits to using numerical formats with lower precision than the 32-bit floating-point or higher precision such as 64-bit floating-point.
1414

‎docs/source/common/checkpointing.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@
66

77
.. _checkpointing:
88

9-
##############################
10-
Saving and Loading Checkpoints
11-
##############################
9+
#############
10+
Checkpointing
11+
#############
1212

1313
Lightning provides functions to save and load checkpoints.
1414

‎docs/source/common_usecases.rst

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
:orphan:
2+
3+
Common use cases
4+
================
5+
6+
.. include:: links.rst
7+
8+
.. raw:: html
9+
10+
<div class="tutorials-callout-container">
11+
<div class="row">
12+
13+
.. Add callout items below this line
14+
15+
.. customcalloutitem::
16+
:description: Learn to train Lightning models on the cloud
17+
:header: Cloud training
18+
:button_link: clouds/cloud_training.html
19+
:card_style: text-container-small
20+
21+
.. customcalloutitem::
22+
:description: Lightning checkpoints have everything you need to save and restore your models
23+
:header: Checkpointing
24+
:button_link: common/checkpointing.html
25+
:card_style: text-container-small
26+
27+
.. customcalloutitem::
28+
:description: Learn to train on your university or company's cluster
29+
:header: Cluster training
30+
:button_link: clouds/cluster.html
31+
:card_style: text-container-small
32+
33+
.. customcalloutitem::
34+
:description: Tricks for debugging your Lightning Models
35+
:header: Debugging
36+
:button_link: common/debugging.html
37+
:card_style: text-container-small
38+
39+
.. customcalloutitem::
40+
:description: Save time and money by training until key metrics stop improving or time has elapsed
41+
:header: Early stopping
42+
:button_link: common/early_stopping.html
43+
:card_style: text-container-small
44+
45+
.. customcalloutitem::
46+
:description: Here you'll find the latest SOTA training techniques such as SWA, accumulated gradients, etc...
47+
:header: Effective training techniques
48+
:button_link: advanced/training_tricks.html
49+
:card_style: text-container-small
50+
51+
.. customcalloutitem::
52+
:description: Avoid over-fitting (memorizing the dataset) with these techniques
53+
:header: Evaluation
54+
:button_link: common/evaluation.html
55+
:card_style: text-container-small
56+
57+
.. customcalloutitem::
58+
:description: Before coding a complex model, use lightning-flash to create a baseline in a few lines of code
59+
:header: Fast baselines
60+
:button_link: ecosystem/flash.html
61+
:card_style: text-container-small
62+
63+
.. customcalloutitem::
64+
:description: Enable fault-tolerant training in clusters/clouds where machines might fail (ie: pre-emtible machines)
65+
:header: Fault-tolerant training
66+
:button_link: advanced/fault_tolerant_training.html
67+
:card_style: text-container-small
68+
69+
.. customcalloutitem::
70+
:description: Make your models more flexible by enabling command-line arguments
71+
:header: Hyperparameters (via command-line)
72+
:button_link: common/hyperparameters.html
73+
:card_style: text-container-small
74+
75+
.. customcalloutitem::
76+
:description: Use the latest tricks to easily productionize your Lightning models
77+
:header: Inference in Production
78+
:button_link: common/production_inference.html
79+
:card_style: text-container-small
80+
81+
.. customcalloutitem::
82+
:description: Reduce configuration boilerplate with the Lightning CLI
83+
:header: Lightning CLI
84+
:button_link: common/lightning_cli.html
85+
:card_style: text-container-small
86+
87+
.. customcalloutitem::
88+
:description: Visualize your machine learning experiments with these experiment managers
89+
:header: Loggers (experiment managers)
90+
:button_link: common/loggers.html
91+
:card_style: text-container-small
92+
93+
.. customcalloutitem::
94+
:description: Use the model registry to mix and match your models and Datamodules
95+
:header: Model and Datamodule registry
96+
:button_link: common/lightning_cli.html#multiple-models-and-or-datasets
97+
:card_style: text-container-small
98+
99+
.. customcalloutitem::
100+
:description: Train 1TB+ parameter models with these advanced built-in techniques
101+
:header: Model parallelism
102+
:button_link: advanced/model_parallel.html
103+
:card_style: text-container-small
104+
105+
.. customcalloutitem::
106+
:description: Increase batch-sizes and improve speeds by training using 16-bit precision and more
107+
:header: N-Bit Precision
108+
:button_link: advanced/precision.html
109+
:card_style: text-container-small
110+
111+
.. customcalloutitem::
112+
:description: Enable manual optimization to fully control the optimization procedure for advanced research
113+
:header: Manual Optimization
114+
:button_link: common/optimization.html
115+
:card_style: text-container-small
116+
117+
.. customcalloutitem::
118+
:description: Use these profilers to find bottlenecks in your model
119+
:header: Profiling
120+
:button_link: advanced/profiler.html
121+
:card_style: text-container-small
122+
123+
.. customcalloutitem::
124+
:description: Use these built-in progress bars or learn how to make your own!
125+
:header: Progress Bar
126+
:button_link: common/progress_bar.html
127+
:card_style: text-container-small
128+
129+
.. customcalloutitem::
130+
:description: Compress model sizes to speed up model inference for deployment without loss of performance (accuracy)
131+
:header: Pruning and Quantization
132+
:button_link: advanced/pruning_quantization.html
133+
:card_style: text-container-small
134+
135+
.. customcalloutitem::
136+
:description: Work with data on any local or cloud filesystem such as S3 on AWS, GCS on Google Cloud, or ADL on Azure
137+
:header: Remote filesystems
138+
:button_link: common/remote_fs.html
139+
:card_style: text-container-small
140+
141+
.. customcalloutitem::
142+
:description: Building the next Deepspeed, FSDP or fancy scaling technique? Add them to Lightning here
143+
:header: Strategy registry
144+
:button_link: advanced/strategy_registry.html
145+
:card_style: text-container-small
146+
147+
.. customcalloutitem::
148+
:description: Simplify metrics calculations to scale-proof your models
149+
:header: Torchmetrics
150+
:button_link: ecosystem/metrics.html
151+
:card_style: text-container-small
152+
153+
.. customcalloutitem::
154+
:description: Use models training on large datasets to achieve better results when you don't have much data
155+
:header: Transfer learning (finetuning)
156+
:button_link: advanced/transfer_learning.html
157+
:card_style: text-container-small
158+
159+
160+
.. raw:: html
161+
162+
</div>
163+
</div>
164+
165+
.. End of callout item section

‎docs/source/conf.py

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,14 @@
2121

2222
import pt_lightning_sphinx_theme
2323

24+
# -----------------------
25+
# VARIABLES WHEN WORKING ON DOCS... MAKE THIS TRUE TO BUILD FASTER
26+
# -----------------------
27+
_PL_FAST_DOCS_DEV = bool(int(os.getenv("PL_FAST_DOCS_DEV", 0)))
28+
29+
# -----------------------
30+
# BUILD stuff
31+
# -----------------------
2432
PATH_HERE = os.path.abspath(os.path.dirname(__file__))
2533
PATH_ROOT = os.path.join(PATH_HERE, "..", "..")
2634
PATH_RAW_NB = os.path.join(PATH_ROOT, "_notebooks")
@@ -29,6 +37,7 @@
2937

3038
_SHOULD_COPY_NOTEBOOKS = True
3139

40+
3241
try:
3342
from assistant import AssistantCLI
3443
except ImportError:
@@ -158,6 +167,11 @@ def _transform_changelog(path_in: str, path_out: str) -> None:
158167
"notebooks/sample-template*",
159168
]
160169

170+
if _PL_FAST_DOCS_DEV:
171+
exclude_patterns.append("notebooks/*")
172+
exclude_patterns.append("tutorials.rst")
173+
174+
161175
# The name of the Pygments (syntax highlighting) style to use.
162176
pygments_style = None
163177

@@ -170,6 +184,7 @@ def _transform_changelog(path_in: str, path_out: str) -> None:
170184
# https://sphinx-themes.org
171185
html_theme = "pt_lightning_sphinx_theme"
172186
html_theme_path = [pt_lightning_sphinx_theme.get_html_theme_path()]
187+
# html_theme_path = ["/Users/williamfalcon/Developer/opensource/lightning_sphinx_theme"]
173188

174189
# Theme options are theme-specific and customize the look and feel of a theme
175190
# further. For a list of options available for each theme, see the

0 commit comments

Comments
 (0)